From 278b7528ac60d9c838f56981d1f2c2c2f3b77bf7 Mon Sep 17 00:00:00 2001 From: myk002 Date: Wed, 21 Sep 2022 17:53:51 -0700 Subject: [PATCH] implement basic domain index structure --- conf.py | 59 ++------------------ docs/Core.rst | 2 +- docs/Memory-research.rst | 2 +- docs/Tags.rst | 54 +++++++++--------- docs/sphinx_extensions/dfhack/tool_docs.py | 64 ++++++++++++++++++++-- library/lua/helpdb.lua | 2 +- 6 files changed, 94 insertions(+), 89 deletions(-) diff --git a/conf.py b/conf.py index 0170a872b..01c358153 100644 --- a/conf.py +++ b/conf.py @@ -58,9 +58,6 @@ def doc_dir(dirname, files, prefix): def doc_all_dirs(): """Collect the commands and paths to include in our docs.""" tools = [] - # TODO: as we scan the docs, parse out the tags and short descriptions and - # build a map for use in generating the tags pages and links in the tool - # doc footers for root, _, files in os.walk('docs/builtins'): tools.extend(doc_dir(root, files, os.path.relpath(root, 'docs/builtins'))) for root, _, files in os.walk('docs/plugins'): @@ -69,59 +66,16 @@ def doc_all_dirs(): tools.extend(doc_dir(root, files, os.path.relpath(root, 'scripts/docs'))) return tuple(tools) -DOC_ALL_DIRS = doc_all_dirs() - - -def get_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: - line = line.strip() - m = re.match(group_re, line) - if m: - 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) - 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(): """ Creates a file for each tool with the ".. include::" directives to pull in - the original documentation. Then we generate a label and useful info in the - footer. + the original documentation. """ - for k in DOC_ALL_DIRS: + for k in doc_all_dirs(): header = ':orphan:\n' label = ('.. _{name}:\n\n').format(name=k[0]) include = ('.. include:: /{path}\n\n').format(path=k[1]) - # 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 os.makedirs(os.path.join('docs/tools', os.path.dirname(k[0])), mode=0o755, exist_ok=True) with write_file_if_changed('docs/tools/{}.rst'.format(k[0])) as outfile: @@ -131,9 +85,8 @@ def write_tool_docs(): outfile.write(include) -# Actually call the docs generator and run test write_tool_docs() -generate_tag_indices() + # -- General configuration ------------------------------------------------ @@ -315,11 +268,9 @@ html_sidebars = { ] } -# If false, no module index is generated. -html_domain_indices = False - -# If false, no genindex.html is generated. +# generate indices html_use_index = True +html_domain_indices = True # don't link to rst sources in the generated pages html_show_sourcelink = False diff --git a/docs/Core.rst b/docs/Core.rst index e03a7fcba..012236d59 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -185,7 +185,7 @@ where ``*`` can be any string, including the empty string. A world being loaded can mean a fortress, an adventurer, or legends mode. These files are best used for non-persistent commands, such as setting -a `tag/bugfix` script to run on `repeat`. +a `bugfix-tag-index` script to run on `repeat`. .. _onMapLoad.init: diff --git a/docs/Memory-research.rst b/docs/Memory-research.rst index d9c0833e3..c4c7aeb63 100644 --- a/docs/Memory-research.rst +++ b/docs/Memory-research.rst @@ -63,7 +63,7 @@ are not built by default, but can be built by setting the ``BUILD_DEVEL`` Scripts ~~~~~~~ -Several `development tools ` can be useful for memory research. +Several `development tools ` can be useful for memory research. These include (but are not limited to): - `devel/dump-offsets` diff --git a/docs/Tags.rst b/docs/Tags.rst index 9f3906d58..14a12f411 100644 --- a/docs/Tags.rst +++ b/docs/Tags.rst @@ -13,36 +13,36 @@ 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/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/embark`: Tools that are useful while on the fort embark screen or while creating an adventurer. -- `tag/fort`: Tools that are useful while in fort mode. -- `tag/legends`: Tools that are useful while in legends mode. +- `adventure-tag-index`: 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! +- `dfhack-tag-index`: 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.) +- `embark-tag-index`: Tools that are useful while on the fort embark screen or while creating an adventurer. +- `fort-tag-index`: Tools that are useful while in fort mode. +- `legends-tag-index`: Tools that are useful while in legends mode. "why" tags ---------- -- `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. -- `tag/auto`: Tools that run in the background and automatically manage routine, toilsome aspects of your fortress. -- `tag/bugfix`: Tools that fix specific bugs, either permanently or on-demand. -- `tag/design`: Tools that help you design your fort. -- `tag/dev`: Tools that are useful when developing scripts or mods. -- `tag/fps`: Tools that help you manage FPS drop. -- `tag/gameplay`: Tools that introduce new gameplay elements. -- `tag/inspection`: Tools that let you view information that is otherwise difficult to find. -- `tag/productivity`: Tools that help you do things that you could do manually, but using the tool is better and faster. +- `armok-tag-index`: Tools that give you complete control over an aspect of the game or provide access to information that the game intentionally keeps hidden. +- `auto-tag-index`: Tools that run in the background and automatically manage routine, toilsome aspects of your fortress. +- `bugfix-tag-index`: Tools that fix specific bugs, either permanently or on-demand. +- `design-tag-index`: Tools that help you design your fort. +- `dev-tag-index`: Tools that are useful when developing scripts or mods. +- `fps-tag-index`: Tools that help you manage FPS drop. +- `gameplay-tag-index`: Tools that introduce new gameplay elements. +- `inspection-tag-index`: Tools that let you view information that is otherwise difficult to find. +- `productivity-tag-index`: Tools that help you do things that you could do manually, but using the tool is better and faster. "what" tags ----------- -- `tag/animals`: Tools that interact with animals. -- `tag/buildings`: Tools that interact with buildings and furniture. -- `tag/graphics`: Tools that interact with game graphics. -- `tag/interface`: Tools that interact with or extend the DF user interface. -- `tag/items`: Tools that interact with in-game items. -- `tag/jobs`: Tools that interact with jobs. -- `tag/labors`: Tools that deal with labor assignment. -- `tag/map`: Tools that interact with the game map. -- `tag/military`: Tools that interact with the military. -- `tag/plants`: Tools that interact with trees, shrubs, and crops. -- `tag/stockpiles`: Tools that interact wtih stockpiles. -- `tag/units`: Tools that interact with units. -- `tag/workorders`: Tools that interact with workorders. +- `animals-tag-index`: Tools that interact with animals. +- `buildings-tag-index`: Tools that interact with buildings and furniture. +- `graphics-tag-index`: Tools that interact with game graphics. +- `interface-tag-index`: Tools that interact with or extend the DF user interface. +- `items-tag-index`: Tools that interact with in-game items. +- `jobs-tag-index`: Tools that interact with jobs. +- `labors-tag-index`: Tools that deal with labor assignment. +- `map-tag-index`: Tools that interact with the game map. +- `military-tag-index`: Tools that interact with the military. +- `plants-tag-index`: Tools that interact with trees, shrubs, and crops. +- `stockpiles-tag-index`: Tools that interact wtih stockpiles. +- `units-tag-index`: Tools that interact with units. +- `workorders-tag-index`: Tools that interact with workorders. diff --git a/docs/sphinx_extensions/dfhack/tool_docs.py b/docs/sphinx_extensions/dfhack/tool_docs.py index 6f5df5568..cff47de79 100644 --- a/docs/sphinx_extensions/dfhack/tool_docs.py +++ b/docs/sphinx_extensions/dfhack/tool_docs.py @@ -5,7 +5,8 @@ import logging import os -from typing import List, Optional, Type +import re +from typing import Iterable, List, Optional, Tuple, Type import docutils.nodes as nodes from docutils.nodes import Node @@ -13,13 +14,13 @@ import docutils.parsers.rst.directives as rst_directives import sphinx import sphinx.addnodes as addnodes import sphinx.directives +from sphinx.domains import Domain, Index, IndexEntry from sphinx.util.docutils import SphinxDirective from sphinx.util.nodes import process_index_entry import dfhack.util - logger = sphinx.util.logging.getLogger(__name__) @@ -165,7 +166,7 @@ class DFHackToolDirective(DFHackToolDirectiveBase): addnodes.pending_xref(tag, nodes.inline(text=tag), **{ 'reftype': 'ref', 'refdomain': 'std', - 'reftarget': 'tag/' + tag, + 'reftarget': tag + '-tag-index', 'refexplicit': False, 'refwarn': True, }), @@ -202,6 +203,56 @@ class DFHackCommandDirective(DFHackToolDirectiveBase): return ret_nodes +def get_tags(): + groups = {} + group_re = re.compile(r'"([^"]+)"') + tag_re = re.compile(r'- `([^`]+)-tag-index`: (.*)') + with open('docs/Tags.rst') as f: + lines = f.readlines() + for line in lines: + line = line.strip() + m = re.match(group_re, line) + if m: + 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_index(self, docnames: Optional[Iterable[str]] = None) -> Tuple[List[Tuple[str, List[IndexEntry]]], bool]: + return [('A', [['name', 0, '', '', '', '', '']])], False + + +def init_tag_indices(app): + os.makedirs('docs/tags', mode=0o755, exist_ok=True) + tag_groups = get_tags() + for tag_group in tag_groups: + with dfhack.util.write_file_if_changed(('docs/tags/by{group}.rst').format(group=tag_group)) as topidx: + for tag_tuple in tag_groups[tag_group]: + tag, desc = tag_tuple[0], tag_tuple[1] + topidx.write(('- `{name} <{name}-tag-index>`\n').format(name=tag)) + topidx.write((' {desc}\n').format(desc=desc)) + + domain_class = type(tag+'Domain', (Domain, ), { + 'name': tag, + 'label': 'Container domain for tag: ' + tag, + }) + index_class = type(tag+'Index', (Index, ), { + 'name': 'tag-index', + 'localname': tag + ' tag index', + 'shortname': tag, + 'desc': desc, + 'generate': generate_tag_index, + }) + app.add_domain(domain_class) + app.add_index_to_domain(tag, index_class) + + def register(app): app.add_directive('dfhack-tool', DFHackToolDirective) app.add_directive('dfhack-command', DFHackCommandDirective) @@ -212,11 +263,14 @@ def register(app): def setup(app): app.connect('builder-inited', register) + init_tag_indices(app) + # TODO: re-enable once detection is corrected # app.connect('build-finished', lambda *_: check_missing_keybinds()) + # TODO: implement parallel builds so we can set these back to True return { 'version': '0.1', - 'parallel_read_safe': True, - 'parallel_write_safe': True, + 'parallel_read_safe': False, + 'parallel_write_safe': False, } diff --git a/library/lua/helpdb.lua b/library/lua/helpdb.lua index c39d3ba80..ac6adb55d 100644 --- a/library/lua/helpdb.lua +++ b/library/lua/helpdb.lua @@ -396,7 +396,7 @@ local function initialize_tags() desc = desc .. ' ' .. line tag_index[tag].description = desc else - _,_,tag,desc = line:find('^%* (%w+): (.+)') + _,_,tag,desc = line:find('^%* (%w+)[^:]*: (.+)') if not tag then goto continue end tag_index[tag] = {description=desc} in_desc = true