Attempt to port keybinding documentation verification to new extension

Likely requires a sphinx Domain to work with parallel builds properly
develop
lethosor 2022-08-07 02:16:38 -04:00
parent 7651d301d2
commit 6b32e008b3
No known key found for this signature in database
GPG Key ID: 76A269552F4F58C1
2 changed files with 15 additions and 15 deletions

@ -126,24 +126,9 @@ def write_tool_docs():
outfile.write(include) 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 # Actually call the docs generator and run test
write_tool_docs() write_tool_docs()
generate_tag_indices() generate_tag_indices()
#all_keybinds_documented() # comment out while we're transitioning
# -- General configuration ------------------------------------------------ # -- General configuration ------------------------------------------------

@ -3,6 +3,7 @@
# https://www.sphinx-doc.org/en/master/development/tutorials/recipe.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 # https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-directives
import logging
import os import os
from typing import List from typing import List
@ -15,7 +16,10 @@ import sphinx.directives
import dfhack.util import dfhack.util
logger = sphinx.util.logging.getLogger(__name__)
_KEYBINDS = {} _KEYBINDS = {}
_KEYBINDS_RENDERED = set() # commands whose keybindings have been rendered
def scan_keybinds(root, files, keybindings): def scan_keybinds(root, files, keybindings):
"""Add keybindings in the specified files to the """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]: def render_dfhack_keybind(command) -> List[nodes.paragraph]:
_KEYBINDS_RENDERED.add(command)
out = [] out = []
if command not in _KEYBINDS: if command not in _KEYBINDS:
return out return out
@ -64,6 +69,13 @@ def render_dfhack_keybind(command) -> List[nodes.paragraph]:
return out 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 # pylint:disable=unused-argument,dangerous-default-value,too-many-arguments
def dfhack_keybind_role(role, rawtext, text, lineno, inliner, def dfhack_keybind_role(role, rawtext, text, lineno, inliner,
options={}, content=[]): options={}, content=[]):
@ -153,6 +165,9 @@ def register(app):
def setup(app): def setup(app):
app.connect('builder-inited', register) app.connect('builder-inited', register)
# TODO: re-enable once detection is corrected
# app.connect('build-finished', lambda *_: check_missing_keybinds())
return { return {
'version': '0.1', 'version': '0.1',
'parallel_read_safe': True, 'parallel_read_safe': True,