get rid of tool TOC, use genindex

also add a stub role for dfhack-tag

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)

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
 ============

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 <genindex>`.
 
-- 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

docs/index-tools.rst

@@ -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/*/*

index.rst

@@ -15,10 +15,9 @@ Quick Links
 
 * `Downloads <https://www.github.com/DFHack/dfhack/releases>`_
 * `Installation guide <installing>`
-* `Source code <https://www.github.com/DFHack/dfhack>`_
-  (**important:** read `compile` before attempting to build from source)
-* `Bay 12 forums thread <https://dfhack.org/bay12>`_
-* `Bug tracker <https://www.github.com/DFHack/dfhack/issues>`_
+* `Getting help <support>`
+* :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