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

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

@ -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 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 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 `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 DFHack tools by game mode
------------------------- -------------------------

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