DFHack
Design Core Help API
The launcher will need to create a map of command names to (list of tags, brief description, help text), so it can generate the other required internal data structures. Script help text can already be retrieved through the dfhack.script_help() API, but we currently have no way to programmatically access the full help text for plugins.
In addition, we will need an API that can retrieve the brief descriptions and the new tags metadata for scripts and plugins.
The plugin command registration API will need to be modified to add tags. We also need to think about how the current plugin documentation in Plugins.rst can be made accessible to the launcher while still being rendered for the online documentation.
Alternate idea: we use sphinx to render the help content to text format, then we just read the text files. That way we won't have to deal with RST formatting markers in our GUI. This would also help with cleaning up the output of script help text. Plugin documentation would still need to be reorganized so we can find the help text for each plugin (or is that true? can we easily extract the documentation for each command from Plugins.rst?)
Ok, I did some research on how we currently process help text. How's this for a plan:
- Move plugin help text to the cpp files. Use block comments at the top of the file, similar to how we already process script files. There will be one help section per command defined in the plugin.
- Assign tags to every command (including scripts). Add them as a line of text in the help text under the main header for each command. This way they can be extracted by sphinx.
- Generate documentation pages, one per command, from the rst in the script and cpp files. Create tag maps as we generate the pages. Extract the first sentence of the help text to use as the short description. Error if a command has no tags or short description.
- Generate a page for each tag, listing the commands with that tag and including the other tags for each command and their short descriptions.
- Generate an all inclusive index of all commands, including their tags and short descriptions
- Modify our docs build to produce text output in addition to HTML output
- Modify core and dfhack.lua to read help text from the rendered text docs, including the short descriptions output in
ls(we can keep the current convention for scripts where the short description is taken from the first line comment). We can fall back to reading script files directly for scripts that don't exist in the docs or whose mtime is more recent than the docs.
Format for help text section:
/***** mycommand
mycommand
---------
tags: tag1 tag2 ...
Brief description (max 5 lines).
Usage::
mycommand literal <param> [optional element]
mycommand alternate forms
Options:
Format TBD
Examples:
Format TBD
Other sections...
*****/
the plan, v2:
- Move plugin and script help text to
docs/tools/<command>.rst. - Assign tags to every command. Add them as a line of text in the help text under the main header for each command. Extract the tags in
conf.pyand create tag maps. Extract the first sentence of the help text to use as the short description. Error if a command has no tags or short description. - Generate a page for each tag, listing the commands with that tag and including the other tags for each command and their short descriptions.
- Generate an all inclusive index of all commands, including their tags and short descriptions
- Modify our docs build to produce text output in addition to HTML output
- Modify core and dfhack.lua to read help text from the rendered text docs, including the short descriptions output in
ls(we can keep the current convention for scripts where the short description is taken from the first line comment). We can fall back to reading script files directly for scripts that don't exist in the docs or whose mtime is more recent than the docs.
Format for help text section:
mycommand
=========
tags: tag1 tag2 ...
:dfhack-keybind:`mycommand`
Brief description (max 5 lines).
Usage::
mycommand literal <descriptive param> [optional element]
mycommand alternate forms
Options:
Format TBD
Examples:
Format TBD
Other sections...
*****/
Plugins that provide no commands can have a pseudo command that is the plugin name so we can document what it does when enabled