MetzNet
/
dfhack
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

use a domain index instead of the genindex

develop
myk002 2022-09-23 10:10:28 -07:00
parent a92e5d1f74
commit 1b9cd83009
No known key found for this signature in database
GPG Key ID: 8A39CA0FA0C16E78
3 changed files with 30 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
conf.py
Unescape Escape View File

@ -268,8 +268,8 @@ html_sidebars = {
]
}
# generate indices
html_use_index = True
# generate domain indices but not the (unused) genindex
html_use_index = False
html_domain_indices = True
# don't link to rst sources in the generated pages

2
docs/Tools.rst
Unescape Escape View File

@ -34,7 +34,7 @@ DFHack tools are tagged with categories to make them easier to find. These
categories are listed in the next few sections. Note that a tool can belong to
more than one category. If you already know what you're looking for, try the
`search` or Ctrl-F on this page. If you'd like to see the full list of tools in
one flat list, please refer to the `annotated index <genindex>`.
one flat list, please refer to the `annotated index <all-tag-index>`.
DFHack tools by game mode
-------------------------

57
docs/sphinx_extensions/dfhack/tool_docs.py
Unescape Escape View File

@ -52,18 +52,6 @@ def make_summary(builder: sphinx.builders.Builder, summary: str) -> nodes.paragr
para += nodes.inline(text=summary)
return para
def make_index(directive: SphinxDirective, name: str, summary: str) -> List[Node]:
targetid = 'index-%s' % directive.env.new_serialno('index')
targetnode = nodes.target('', '', ids=[targetid])
directive.state.document.note_explicit_target(targetnode)
indexnode = addnodes.index()
indexnode['entries'] = []
indexnode['inline'] = False
directive.set_source_info(indexnode)
entry_text = 'single: {}; {}'.format(name, summary)
indexnode['entries'].extend(process_index_entry(entry_text, targetnode['ids'][0]))
return [indexnode, targetnode]
_KEYBINDS = {}
_KEYBINDS_RENDERED = set() # commands whose keybindings have been rendered
@ -137,6 +125,10 @@ class DFHackToolDirectiveBase(sphinx.directives.ObjectDescription):
else:
return parts[-1]
def add_index_entry(self, name, tag) -> None:
indexdata = (name, self.options.get('summary', ''), '', self.env.docname, '', 0)
self.env.domaindata[tag]['objects'].append(indexdata)
@staticmethod
def wrap_box(*children: List[nodes.Node]) -> nodes.Admonition:
return nodes.topic('', *children, classes=['dfhack-tool-summary'])
@ -173,14 +165,12 @@ class DFHackToolDirective(DFHackToolDirectiveBase):
}),
nodes.inline(text=' | '),
]
name = self.get_name_or_docname()
indexdata = (name, self.options.get('summary', ''), '', self.env.docname, '', 0)
self.env.domaindata[tag]['objects'].append(indexdata)
self.add_index_entry(self.get_name_or_docname(), tag)
tag_paragraph.pop()
ret_nodes = [tag_paragraph]
if 'no-command' in self.options:
ret_nodes += make_index(self, self.get_name_or_docname() + ' (plugin)', self.options.get('summary', ''))
self.add_index_entry(self.get_name_or_docname() + ' (plugin)', 'all')
ret_nodes += [make_summary(self.env.app.builder, self.options.get('summary', ''))]
return ret_nodes
@ -198,13 +188,12 @@ class DFHackCommandDirective(DFHackToolDirectiveBase):
def render_content(self) -> List[nodes.Node]:
command = self.get_name_or_docname()
ret_nodes = [self.make_labeled_paragraph('Command', command, content_class=nodes.literal)]
ret_nodes += make_index(self, command, self.options.get('summary', ''))
ret_nodes += [
self.add_index_entry(command, 'all')
return [
self.make_labeled_paragraph('Command', command, content_class=nodes.literal),
make_summary(self.env.app.builder, self.options.get('summary', '')),
*render_dfhack_keybind(command, builder=self.env.app.builder),
]
return ret_nodes
def get_tags():
@ -250,17 +239,7 @@ def tag_index_generate(self, docnames: Optional[Iterable[str]] = None) -> Tuple[
IndexEntry(name, 0, docname, '', '', '', desc))
return (sorted(content.items()), 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))
def register_index(app, tag, title):
domain_class = type(tag+'Domain', (Domain, ), {
'name': tag,
'label': 'Container domain for tag: ' + tag,
@ -270,25 +249,35 @@ def init_tag_indices(app):
})
index_class = type(tag+'Index', (Index, ), {
'name': 'tag-index',
'localname': '"' + tag + '" tag index',
'localname': title,
'shortname': tag,
'desc': desc,
'generate': tag_index_generate,
})
app.add_domain(domain_class)
app.add_index_to_domain(tag, index_class)
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))
register_index(app, tag, '"%s" tag index' % tag)
def register(app):
app.add_directive('dfhack-tool', DFHackToolDirective)
app.add_directive('dfhack-command', DFHackCommandDirective)
_KEYBINDS.update(scan_all_keybinds(os.path.join(dfhack.util.DFHACK_ROOT, 'data', 'init')))
def setup(app):
app.connect('builder-inited', register)
register_index(app, 'all', 'Index of DFHack tools')
init_tag_indices(app)
# TODO: re-enable once detection is corrected