Initial attempt at dfhack-tool directive

Doesn't appear to produce headings that can be used as link targets...
develop
lethosor 2022-07-27 02:17:21 -04:00
parent 8f332c5925
commit c44c8721c9
No known key found for this signature in database
GPG Key ID: 76A269552F4F58C1
4 changed files with 69 additions and 0 deletions

@ -237,6 +237,7 @@ extensions = [
'sphinx.ext.extlinks', 'sphinx.ext.extlinks',
'dfhack.changelog', 'dfhack.changelog',
'dfhack.lexer', 'dfhack.lexer',
'dfhack.tool_docs',
] ]
sphinx_major_version = sphinx.version_info[0] sphinx_major_version = sphinx.version_info[0]

@ -3,6 +3,9 @@
**Tags:** `tag/fort`, `tag/mod`, `tag/map` **Tags:** `tag/fort`, `tag/mod`, `tag/map`
:dfhack-keybind:`3dveins` :dfhack-keybind:`3dveins`
.. dfhack-tool:: 3dveins
:tags: foo, bar
:index:`Rewrite layer veins to expand in 3D space. :index:`Rewrite layer veins to expand in 3D space.
<3dveins; Rewrite layer veins to expand in 3D space.>` Existing, flat veins <3dveins; Rewrite layer veins to expand in 3D space.>` Existing, flat veins
are removed and new 3D veins that naturally span z-levels are generated in are removed and new 3D veins that naturally span z-levels are generated in

@ -0,0 +1,52 @@
# useful references:
# https://www.sphinx-doc.org/en/master/extdev/appapi.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
import docutils.nodes as nodes
# import docutils.parsers.rst.directives as rst_directives
import sphinx
import sphinx.directives
import dfhack.util
class DFHackToolDirective(sphinx.directives.ObjectDescription):
has_content = False
required_arguments = 1
option_spec = {
'tags': dfhack.util.directive_arg_str_list,
}
def run(self):
tool_name = self.get_signatures()[0]
tag_nodes = [nodes.strong(text='Tags: ')]
for tag in self.options['tags']:
tag_nodes += [
nodes.literal(tag, tag),
nodes.inline(text=' | '),
]
tag_nodes.pop()
return [
nodes.title(text=tool_name),
nodes.paragraph('', '', *tag_nodes),
]
# simpler but always renders as "inline code" (and less customizable)
# def handle_signature(self, sig, signode):
# signode += addnodes.desc_name(text=sig)
# return sig
def register(app):
app.add_directive('dfhack-tool', DFHackToolDirective)
def setup(app):
app.connect('builder-inited', register)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}

@ -5,3 +5,16 @@ DOCS_ROOT = os.path.join(DFHACK_ROOT, 'docs')
if not os.path.isdir(DOCS_ROOT): if not os.path.isdir(DOCS_ROOT):
raise ReferenceError('docs root not found: %s' % DOCS_ROOT) raise ReferenceError('docs root not found: %s' % DOCS_ROOT)
# directive argument helpers (supplementing docutils.parsers.rst.directives)
def directive_arg_str_list(argument):
"""
Converts a space- or comma-separated list of values into a Python list
of strings.
(Directive option conversion function.)
"""
if ',' in argument:
entries = argument.split(',')
else:
entries = argument.split()
return [entry.strip() for entry in entries]