Initial attempt at dfhack-tool directive

Doesn't appear to produce headings that can be used as link targets...

conf.py

@@ -237,6 +237,7 @@ extensions = [
     'sphinx.ext.extlinks',
     'dfhack.changelog',
     'dfhack.lexer',
+    'dfhack.tool_docs',
 ]
 
 sphinx_major_version = sphinx.version_info[0]

docs/plugins/3dveins.rst

@@ -3,6 +3,9 @@
 **Tags:** `tag/fort`, `tag/mod`, `tag/map`
 :dfhack-keybind:`3dveins`
 
+.. dfhack-tool:: 3dveins
+    :tags: foo, bar
+
 :index:`Rewrite layer veins to expand in 3D space.
 <3dveins; Rewrite layer veins to expand in 3D space.>` Existing, flat veins
 are removed and new 3D veins that naturally span z-levels are generated in

docs/sphinx_extensions/dfhack/tool_docs.py

@@ -0,0 +1,52 @@
+# useful references:
+#   https://www.sphinx-doc.org/en/master/extdev/appapi.html
+#   https://www.sphinx-doc.org/en/master/development/tutorials/recipe.html
+#   https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-directives
+
+import docutils.nodes as nodes
+# import docutils.parsers.rst.directives as rst_directives
+import sphinx
+import sphinx.directives
+
+import dfhack.util
+
+class DFHackToolDirective(sphinx.directives.ObjectDescription):
+    has_content = False
+    required_arguments = 1
+    option_spec = {
+        'tags': dfhack.util.directive_arg_str_list,
+    }
+
+    def run(self):
+        tool_name = self.get_signatures()[0]
+
+        tag_nodes = [nodes.strong(text='Tags: ')]
+        for tag in self.options['tags']:
+            tag_nodes += [
+                nodes.literal(tag, tag),
+                nodes.inline(text=' | '),
+            ]
+        tag_nodes.pop()
+
+        return [
+            nodes.title(text=tool_name),
+            nodes.paragraph('', '', *tag_nodes),
+        ]
+
+    # simpler but always renders as "inline code" (and less customizable)
+    # def handle_signature(self, sig, signode):
+    #     signode += addnodes.desc_name(text=sig)
+    #     return sig
+
+
+def register(app):
+    app.add_directive('dfhack-tool', DFHackToolDirective)
+
+def setup(app):
+    app.connect('builder-inited', register)
+
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

docs/sphinx_extensions/dfhack/util.py

@@ -5,3 +5,16 @@ DOCS_ROOT = os.path.join(DFHACK_ROOT, 'docs')
 
 if not os.path.isdir(DOCS_ROOT):
     raise ReferenceError('docs root not found: %s' % DOCS_ROOT)
+
+# directive argument helpers (supplementing docutils.parsers.rst.directives)
+def directive_arg_str_list(argument):
+    """
+    Converts a space- or comma-separated list of values into a Python list
+    of strings.
+    (Directive option conversion function.)
+    """
+    if ',' in argument:
+        entries = argument.split(',')
+    else:
+        entries = argument.split()
+    return [entry.strip() for entry in entries]