organize tags by group, add more info about tools

conf.py

@@ -73,29 +73,40 @@ DOC_ALL_DIRS = doc_all_dirs()
 
 
 def get_tags():
-    tags = []
+    groups = {}
+    group_re = re.compile(r'"([^"]+)"')
     tag_re = re.compile(r'- `tag/([^`]+)`: (.*)')
     with open('docs/Tags.rst') as f:
         lines = f.readlines()
         for line in lines:
-            m = re.match(tag_re, line.strip())
+            line = line.strip()
+            m = re.match(group_re, line)
             if m:
-                tags.append((m.group(1), m.group(2)))
-    return tags
+                group = m.group(1)
+                groups[group] = []
+                continue
+            m = re.match(tag_re, line)
+            if m:
+                tag = m.group(1)
+                desc = m.group(2)
+                groups[group].append((tag, desc))
+    return groups
 
 
 def generate_tag_indices():
     os.makedirs('docs/tags', mode=0o755, exist_ok=True)
-    with write_file_if_changed('docs/tags/index.rst') as topidx:
-        for tag_tuple in get_tags():
-            tag = tag_tuple[0]
-            with write_file_if_changed(('docs/tags/{name}.rst').format(name=tag)) as tagidx:
-                tagidx.write('TODO: add links to the tools that have this tag')
-            topidx.write(('.. _tag/{name}:\n\n').format(name=tag))
-            topidx.write(('{name}\n').format(name=tag))
-            topidx.write(('{underline}\n').format(underline='-'*len(tag)))
-            topidx.write(('{desc}\n\n').format(desc=tag_tuple[1]))
-            topidx.write(('.. include:: /docs/tags/{name}.rst\n\n').format(name=tag))
+    tag_groups = get_tags()
+    for tag_group in tag_groups:
+        with write_file_if_changed(('docs/tags/by{group}.rst').format(group=tag_group)) as topidx:
+            for tag_tuple in tag_groups[tag_group]:
+                tag = tag_tuple[0]
+                with write_file_if_changed(('docs/tags/{name}.rst').format(name=tag)) as tagidx:
+                    tagidx.write('TODO: add links to the tools that have this tag')
+                topidx.write(('.. _tag/{name}:\n\n').format(name=tag))
+                topidx.write(('{name}\n').format(name=tag))
+                topidx.write(('{underline}\n').format(underline='*'*len(tag)))
+                topidx.write(('{desc}\n\n').format(desc=tag_tuple[1]))
+                topidx.write(('.. include:: /docs/tags/{name}.rst\n\n').format(name=tag))
 
 
 def write_tool_docs():

docs/Categories.rst

@@ -1,13 +0,0 @@
-.. _categories:
-
-Tool categories
-===============
-
-DFHack tools are grouped to make them easier to find. Note that a tool can
-belong to more than one category. If you'd like to see the full list of tools
-in one flat list, please refer to the `index <genindex>`.
-
-.. contents:: Contents
-  :local:
-
-.. include:: tags/index.rst

docs/Documentation.rst

@@ -64,8 +64,8 @@ Tags
 
 To make it easier for players to find related commands, all plugins and commands are marked
 with relevant tags. These are used to compile indices and generate cross-links between the
-commands, both in the HTML documents and in-game. See the list of available tags
-`here <categories>` and think about which categories your new tools belongs in.
+commands, both in the HTML documents and in-game. See the list of available `tag-list` and
+think about which categories your new tool belongs in.
 
 Links
 -----

docs/Tags.rst

@@ -1,10 +1,26 @@
 :orphan:
 
+.. _tag-list:
+
+DFHack tool tags
+================
+
+A tool often has at least one tag per group, encompassing when you use the tool,
+why you might want to use it, and what kind of thing you're trying to affect.
+
+See https://docs.google.com/spreadsheets/d/1hiDlo8M_bB_1jE-5HRs2RrrA_VZ4cRu9VXaTctX_nwk/edit#gid=1774645373
+for the tag assignment spreadsheet.
+
+"when" tags
+-----------
 - `tag/adventure`: Tools that are useful while in adventure mode. Note that some tools only tagged with "fort" might also work in adventure mode, but not always in expected ways. Feel free to experiment, though!
 - `tag/fort`: Tools that are useful while in fort mode.
 - `tag/legends`: Tools that are useful while in legends mode.
 - `tag/embark`: Tools that are useful while on the fort embark screen or while creating an adventurer.
 - `tag/dev`: Tools that are useful when developing scripts or mods.
+
+"why" tags
+----------
 - `tag/dfhack`: Tools that you use to run DFHack commands or interact with the DFHack library. This tag also includes tools that help you manage the DF game itself (e.g. settings, saving, etc.)
 - `tag/auto`: Tools that run in the background and automatically manage routine, toilsome aspects of your fortress.
 - `tag/productivity`: Tools that help you do things that you could do manually, but using the tool is better and faster.
@@ -14,6 +30,9 @@
 - `tag/fps`: Tools that help you manage FPS drop.
 - `tag/bugfix`: Tools that fix specific bugs, either permanently or on-demand.
 - `tag/armok`: Tools that give you complete control over an aspect of the game or provide access to information that the game intentionally keeps hidden.
+
+"what" tags
+-----------
 - `tag/animals`: Tools that interact with animals.
 - `tag/buildings`: Tools that interact with buildings and furniture.
 - `tag/stockpiles`: Tools that interact wtih stockpiles.

docs/Tools.rst

@@ -0,0 +1,50 @@
+.. _tools:
+
+DFHack tools
+============
+
+DFHack has **a lot** of tools. This page attempts to make it clearer what they
+are, how they work, and how to find the ones you want.
+
+.. contents:: Contents
+  :local:
+
+What tools are and how they work
+--------------------------------
+
+DFHack is a Dwarf Fortress memory access and modification framework, so DFHack
+tools normally access Dwarf Fortress internals and make some specific changes.
+
+Some tools just make a targeted change when you run them, like `unforbid`, which
+scans through all your items and removes the ``forbidden`` flag from each of
+them.
+
+Some tools need to be enabled, and then they run in the background and make
+changes to the game on your behalf, like `autobutcher`, which monitors your
+livestock population and automatically marks excess animals for butchering.
+
+And some tools just exist to give you information that is otherwise hard to
+come by, like `gui/petitions`, which shows you the active petitions for
+guildhalls and temples that you have agreed to.
+
+Finding the tool you need
+-------------------------
+
+DFHack tools are tagged with categories to make them easier to find. Note that a
+tool can belong to more than one category. If you'd like to see the full list of
+tools in one flat list, please refer to the `index <genindex>`.
+
+DFHack tools by game mode
+-------------------------
+
+.. include:: tags/bywhen.rst
+
+DFHack tools by theme
+---------------------
+
+.. include:: tags/bywhy.rst
+
+DFHack tools by what they affect
+--------------------------------
+
+.. include:: tags/bywhat.rst

index.rst

@@ -28,7 +28,7 @@ User Manual
    /docs/Introduction
    /docs/Installing
    /docs/Core
-   /docs/Categories
+   /docs/Tools
    /docs/guides/index
    /docs/index-dev
    /docs/index-about