From 6a31b316dc694e6a7838b001d649074ee61532b5 Mon Sep 17 00:00:00 2001
From: myk002 <myk002@yahoo.com>
Date: Fri, 22 Jul 2022 14:37:24 -0700
Subject: [PATCH] add structure for category indices

---
 conf.py             | 35 +++++++++++++++++++++++++++++++----
 docs/Categories.rst | 13 +++++++++++++
 docs/Tags.rst       | 20 ++++++--------------
 3 files changed, 50 insertions(+), 18 deletions(-)
 create mode 100644 docs/Categories.rst

diff --git a/conf.py b/conf.py
index abbd1dbb3..e80b5a027 100644
--- a/conf.py
+++ b/conf.py
@@ -126,10 +126,38 @@ def doc_all_dirs():
 
 DOC_ALL_DIRS = doc_all_dirs()
 
+
+def get_tags():
+    tags = []
+    tag_re = re.compile(r'- :dfhack-tag:`([^`]+)`: (.*)')
+    with open('docs/Tags.rst') as f:
+        lines = f.readlines()
+        for line in lines:
+            m = re.match(tag_re, line.strip())
+            if m:
+                tags.append((m.group(1), m.group(2)))
+    return tags
+
+
+def get_open_mode():
+    return 'w' if sys.version_info.major > 2 else 'wb'
+
+
 def generate_tag_indices():
-    #TODO: generate docs/tags/<tag>.rst with the tag description and links to the
-    # tools that have that tag
     os.makedirs('docs/tags', mode=0o755, exist_ok=True)
+    with open('docs/tags/index.rst', get_open_mode()) as topidx:
+        #topidx.write(':orphan:\n\n')
+        for tag_tuple in get_tags():
+            tag = tag_tuple[0]
+            with open(('docs/tags/{name}.rst').format(name=tag),
+                      get_open_mode()) as tagidx:
+                #tagidx.write(':orphan:\n\n')
+                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():
@@ -151,10 +179,9 @@ def write_tool_docs():
         # TODO: generate a footer with links to tools that share at least one
         # tag with this tool. Just the tool names, strung across the bottom of
         # the page in one long wrapped line, similar to how the wiki does it
-        mode = 'w' if sys.version_info.major > 2 else 'wb'
         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:
+        with open('docs/tools/{}.rst'.format(k[0]), get_open_mode()) as outfile:
             outfile.write(header)
             if k[0] != 'search' and k[0] != 'stonesense':
                 outfile.write(label)
diff --git a/docs/Categories.rst b/docs/Categories.rst
new file mode 100644
index 000000000..541f89195
--- /dev/null
+++ b/docs/Categories.rst
@@ -0,0 +1,13 @@
+.. _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,
+please refer to the `index <genindex>`.
+
+.. contents:: Contents
+  :local:
+
+.. include:: tags/index.rst
diff --git a/docs/Tags.rst b/docs/Tags.rst
index de4e4900b..7afbe0a02 100644
--- a/docs/Tags.rst
+++ b/docs/Tags.rst
@@ -1,17 +1,8 @@
-.. _tags:
+:orphan:
 
-Tool categories
-===============
-
-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>`.
-
-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:`adventure`: Tools that are useful while in adventure mode
+- :dfhack-tag:`fort`: Tools that are useful while in fort mode
+- :dfhack-tag:`legends`: Tools that are useful while in 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
@@ -23,5 +14,6 @@ one category.
 - :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:`buildings`: 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
+- :dfhack-tag:`dev`: Tools useful for develpers and modders