diff --git a/conf.py b/conf.py index 0488a2afe..abbd1dbb3 100644 --- a/conf.py +++ b/conf.py @@ -82,7 +82,18 @@ def dfhack_keybind_role_func(role, rawtext, text, lineno, inliner, return [newnode], [] +# pylint:disable=unused-argument,dangerous-default-value,too-many-arguments +def dfhack_tag_role_func(role, rawtext, text, lineno, inliner, + options={}, content=[]): + """Custom role parser for DFHack tags.""" + roles.set_classes(options) + # TODO: link to generated tag index page + newnode = nodes.inline(text, text) + return [newnode], [] + + roles.register_canonical_role('dfhack-keybind', dfhack_keybind_role_func) +roles.register_canonical_role('dfhack-tag', dfhack_tag_role_func) # -- Autodoc for DFhack plugins and scripts ------------------------------- @@ -128,6 +139,7 @@ def write_tool_docs(): footer. """ for k in DOC_ALL_DIRS: + header = ':orphan:\n' label = ('.. _{name}:\n\n').format(name=k[0]) # TODO: can we autogenerate the :dfhack-keybind: line? it would go beneath # the tool header, which is currently in the middle of the included file. @@ -143,6 +155,7 @@ def write_tool_docs(): os.makedirs(os.path.join('docs/tools', os.path.dirname(k[0])), mode=0o755, exist_ok=True) with open('docs/tools/{}.rst'.format(k[0]), mode) as outfile: + outfile.write(header) if k[0] != 'search' and k[0] != 'stonesense': outfile.write(label) outfile.write(include) diff --git a/docs/Introduction.rst b/docs/Introduction.rst index f0dc7a4b6..449f2d38a 100644 --- a/docs/Introduction.rst +++ b/docs/Introduction.rst @@ -59,6 +59,12 @@ used by the DFHack console. * Finally, some commands are persistent once enabled, and will sit in the background managing or changing some aspect of the game if you `enable` them. +.. note:: + In order to avoid user confusion, as a matter of policy all GUI tools + display the word :guilabel:`DFHack` on the screen somewhere while active. + + When that is not appropriate because they merely add keybinding hints to + existing DF screens, they deliberately use red instead of green for the key. Getting help ============ diff --git a/docs/Tags.rst b/docs/Tags.rst index 56e5af650..de4e4900b 100644 --- a/docs/Tags.rst +++ b/docs/Tags.rst @@ -1,23 +1,27 @@ .. _tags: -Tags -==== +Tool categories +=============== -This is the list of tags and their descriptions. +Related DFHack tools are grouped by tags to make them easier to find. If you'd +like to see the full list of commands, please refer to the `index `. -- adventure: Tools relevant to adventure mode -- fort: Tools relevant to fort mode -- legends: Tools relevant to legends mode -- items: Tools that create or modify in-game items -- units: Tools that create or modify units -- jobs: Tools that create or modify jobs -- labors: Tools that deal with labor assignment -- auto: Tools that automatically manage some aspect of your fortress -- map: Map modification -- system: Tools related to working with DFHack commands or the core DFHack library -- productivity: Tools that help you do things that you could do manually, but using the tool is better and faster -- animals: Tools that help you manage animals -- fix: Tools that fix specific bugs -- inspection: Tools that let you inspect game data -- buildings/furniture: Tools that help you work wtih placing or configuring buildings and furniture -- quickfort: Tools that are involved in creating and playing back blueprints +These are the DFHack tool categories. Note that a tool may belong to more than +one category. + +- :dfhack-tag:`adventure`: Tools relevant to adventure mode +- :dfhack-tag:`fort`: Tools relevant to fort mode +- :dfhack-tag:`legends`: Tools relevant to legends mode +- :dfhack-tag:`items`: Tools that create or modify in-game items +- :dfhack-tag:`units`: Tools that create or modify units +- :dfhack-tag:`jobs`: Tools that create or modify jobs +- :dfhack-tag:`labors`: Tools that deal with labor assignment +- :dfhack-tag:`auto`: Tools that automatically manage some aspect of your fortress +- :dfhack-tag:`map`: Map modification +- :dfhack-tag:`system`: Tools related to working with DFHack commands or the core DFHack library +- :dfhack-tag:`productivity`: Tools that help you do things that you could do manually, but using the tool is better and faster +- :dfhack-tag:`animals`: Tools that help you manage animals +- :dfhack-tag:`fix`: Tools that fix specific bugs +- :dfhack-tag:`inspection`: Tools that let you inspect game data +- :dfhack-tag:`buildings/furniture`: Tools that help you work wtih placing or configuring buildings and furniture +- :dfhack-tag:`quickfort`: Tools that are involved in creating and playing back blueprints diff --git a/docs/index-tools.rst b/docs/index-tools.rst deleted file mode 100644 index a9c540d66..000000000 --- a/docs/index-tools.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _tools-index: - -================== -DFHack Tools Index -================== - -These pages contain information about the plugins, scripts, and built-in -commands distributed with DFHack. - -.. toctree:: - :titlesonly: - :glob: - - /docs/tools/* - /docs/tools/*/* diff --git a/index.rst b/index.rst index 3e5cdec5d..843797e4e 100644 --- a/index.rst +++ b/index.rst @@ -15,10 +15,9 @@ Quick Links * `Downloads `_ * `Installation guide ` -* `Source code `_ - (**important:** read `compile` before attempting to build from source) -* `Bay 12 forums thread `_ -* `Bug tracker `_ +* `Getting help ` +* :source:`Source code <>` + (**important:** read `compile` before attempting to build from source.) User Manual =========== @@ -30,25 +29,7 @@ User Manual /docs/Installing /docs/Support /docs/Core + /docs/Tags /docs/guides/index - /docs/index-about /docs/index-dev - -Tools -===== - -DFHack commands, plugins, and scripts are grouped by tags to make it easier to -find groups of related tools. - -.. note:: - In order to avoid user confusion, as a matter of policy all GUI tools - display the word :guilabel:`DFHack` on the screen somewhere while active. - - When that is not appropriate because they merely add keybinding hints to - existing DF screens, they deliberately use red instead of green for the key. - -.. toctree:: - :maxdepth: 1 - - /docs/Tags - /docs/index-tools + /docs/index-about