From 6b32e008b3bfd9eb73535ae69ea82fbf73cc14d0 Mon Sep 17 00:00:00 2001
From: lethosor <lethosor@gmail.com>
Date: Sun, 7 Aug 2022 02:16:38 -0400
Subject: [PATCH] Attempt to port keybinding documentation verification to new
 extension

Likely requires a sphinx Domain to work with parallel builds properly
---
 conf.py                                    | 15 ---------------
 docs/sphinx_extensions/dfhack/tool_docs.py | 15 +++++++++++++++
 2 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/conf.py b/conf.py
index 775f94b68..ff4cdc59d 100644
--- a/conf.py
+++ b/conf.py
@@ -126,24 +126,9 @@ def write_tool_docs():
             outfile.write(include)
 
 
-def all_keybinds_documented():
-    """Check that all keybindings are documented with the :dfhack-keybind:
-    directive somewhere."""
-    undocumented_binds = set(KEYBINDS)
-    tools = set(i[0] for i in DOC_ALL_DIRS)
-    for t in tools:
-        with open(('./docs/tools/{}.rst').format(t)) as f:
-            tool_binds = set(re.findall(':dfhack-keybind:`(.*?)`', f.read()))
-            undocumented_binds -= tool_binds
-    if undocumented_binds:
-        raise ValueError('The following DFHack commands have undocumented '
-                         'keybindings: {}'.format(sorted(undocumented_binds)))
-
-
 # Actually call the docs generator and run test
 write_tool_docs()
 generate_tag_indices()
-#all_keybinds_documented() # comment out while we're transitioning
 
 # -- General configuration ------------------------------------------------
 
diff --git a/docs/sphinx_extensions/dfhack/tool_docs.py b/docs/sphinx_extensions/dfhack/tool_docs.py
index 920bef98e..8c843dce0 100644
--- a/docs/sphinx_extensions/dfhack/tool_docs.py
+++ b/docs/sphinx_extensions/dfhack/tool_docs.py
@@ -3,6 +3,7 @@
 #   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 logging
 import os
 from typing import List
 
@@ -15,7 +16,10 @@ import sphinx.directives
 import dfhack.util
 
 
+logger = sphinx.util.logging.getLogger(__name__)
+
 _KEYBINDS = {}
+_KEYBINDS_RENDERED = set()  # commands whose keybindings have been rendered
 
 def scan_keybinds(root, files, keybindings):
     """Add keybindings in the specified files to the
@@ -45,6 +49,7 @@ def scan_all_keybinds(root_dir):
 
 
 def render_dfhack_keybind(command) -> List[nodes.paragraph]:
+    _KEYBINDS_RENDERED.add(command)
     out = []
     if command not in _KEYBINDS:
         return out
@@ -64,6 +69,13 @@ def render_dfhack_keybind(command) -> List[nodes.paragraph]:
     return out
 
 
+def check_missing_keybinds():
+    # FIXME: _KEYBINDS_RENDERED is empty in the parent process under parallel builds
+    # consider moving to a sphinx Domain to solve this properly
+    for missing_command in sorted(set(_KEYBINDS.keys()) - _KEYBINDS_RENDERED):
+        logger.warning('Undocumented keybindings for command: %s', missing_command)
+
+
 # pylint:disable=unused-argument,dangerous-default-value,too-many-arguments
 def dfhack_keybind_role(role, rawtext, text, lineno, inliner,
                         options={}, content=[]):
@@ -153,6 +165,9 @@ def register(app):
 def setup(app):
     app.connect('builder-inited', register)
 
+    # TODO: re-enable once detection is corrected
+    # app.connect('build-finished', lambda *_: check_missing_keybinds())
+
     return {
         'version': '0.1',
         'parallel_read_safe': True,