Commanding Sublime to display help

Today’s changes bring into the mix some new Sublime Text commands that allow us to interact with the help system in a more natural manner, instead of having to manually import the API into the console and invoke commands directly. At least, that’s the general idea. Currently there are not really any bindings set up, so instead we need to use run_command from the terminal to invoke the help system, but at least there’s no need to import anything.

There’s no animated GIF this time around (even though arguably visually seeing a table of contents has got to be at least twelve times more exciting than watching someone click on links) because it’s late and I get up extra early on the weekends.

The first thing to note is that I changed the name of the classes that already existed to provide commands so that their names start with the prefix Hyperhelp instead of HyperHelp so that the commands that Sublime creates are prefixed with hyperhelp_ instead of hyper_help_. This is just a visual thing but it sort of bothered me that the commands didn’t look as nice as they could.

With that out of the way I implemented a new hyperhelp_reload_index command that uses some of the new API and bound it to the same key that is currently bound to reload the existing help file. This uses a context to only trigger in hyperhelp.json files and triggers the core to reload that help index to make the changes immediately available, which is a boon when debugging.

The next up was a new hyperhelp_topic command, which takes as arguments a package and topic (both strings) and displays the help topic if possible. This is the core of being able to create something like a menu item that opens help to a particular topic or for a package to invoke help for a known help term in a context sensitive fashion.

The last command added was a new hyperhelp_contents command, which is capable of displaying the table of contents for a particular package in a quick panel. This uses the help table of contents from the index, which the help index loader will populate with a list of help topics if the help author decides not to implement the appropriate field to get something more specific.

In both cases, the package argument will be inferred when it’s not provided by looking to see if there is a help view in the current window and if so what package the help file it’s displaying is. In the case of the hyperhelp_contents command, if this is still leaves us without a package the user gets prompted to select one of the available help packages first. You can also force this selection to happen no matter what by passing in an argument.

This means that this command doubles as not only display the contents of a help package but also display the contents of the help system as a whole. This could be handy just to discover what packages are actually providing help, for example.

The help_contents command is currently bound to the ? key if the current file is a help file that’s not being authored, so you can easily jump to another topic by hitting a single key, if desired.

Still to do are some potential menu and command palette entries for these commands to make the integration more complete, but I’ve run out of time for this evening. I’ll do that tomorrow along with working on some more help files that documents things as they currently stand. Along the way I will also likely implement some of the help authoring features to make creating help files easier as well.