get rid of tool TOC, use genindex

also add a stub role for dfhack-tag
develop
myk002 2022-07-22 09:56:23 -07:00
parent 9c7731f072
commit bd58158126
No known key found for this signature in database
GPG Key ID: 8A39CA0FA0C16E78
5 changed files with 47 additions and 58 deletions

@ -82,7 +82,18 @@ def dfhack_keybind_role_func(role, rawtext, text, lineno, inliner,
return [newnode], [] return [newnode], []
# pylint:disable=unused-argument,dangerous-default-value,too-many-arguments
def dfhack_tag_role_func(role, rawtext, text, lineno, inliner,
options={}, content=[]):
"""Custom role parser for DFHack tags."""
roles.set_classes(options)
# TODO: link to generated tag index page
newnode = nodes.inline(text, text)
return [newnode], []
roles.register_canonical_role('dfhack-keybind', dfhack_keybind_role_func) roles.register_canonical_role('dfhack-keybind', dfhack_keybind_role_func)
roles.register_canonical_role('dfhack-tag', dfhack_tag_role_func)
# -- Autodoc for DFhack plugins and scripts ------------------------------- # -- Autodoc for DFhack plugins and scripts -------------------------------
@ -128,6 +139,7 @@ def write_tool_docs():
footer. footer.
""" """
for k in DOC_ALL_DIRS: for k in DOC_ALL_DIRS:
header = ':orphan:\n'
label = ('.. _{name}:\n\n').format(name=k[0]) label = ('.. _{name}:\n\n').format(name=k[0])
# TODO: can we autogenerate the :dfhack-keybind: line? it would go beneath # TODO: can we autogenerate the :dfhack-keybind: line? it would go beneath
# the tool header, which is currently in the middle of the included file. # the tool header, which is currently in the middle of the included file.
@ -143,6 +155,7 @@ def write_tool_docs():
os.makedirs(os.path.join('docs/tools', os.path.dirname(k[0])), os.makedirs(os.path.join('docs/tools', os.path.dirname(k[0])),
mode=0o755, exist_ok=True) mode=0o755, exist_ok=True)
with open('docs/tools/{}.rst'.format(k[0]), mode) as outfile: with open('docs/tools/{}.rst'.format(k[0]), mode) as outfile:
outfile.write(header)
if k[0] != 'search' and k[0] != 'stonesense': if k[0] != 'search' and k[0] != 'stonesense':
outfile.write(label) outfile.write(label)
outfile.write(include) outfile.write(include)

@ -59,6 +59,12 @@ used by the DFHack console.
* Finally, some commands are persistent once enabled, and will sit in the * Finally, some commands are persistent once enabled, and will sit in the
background managing or changing some aspect of the game if you `enable` them. background managing or changing some aspect of the game if you `enable` them.
.. note::
In order to avoid user confusion, as a matter of policy all GUI tools
display the word :guilabel:`DFHack` on the screen somewhere while active.
When that is not appropriate because they merely add keybinding hints to
existing DF screens, they deliberately use red instead of green for the key.
Getting help Getting help
============ ============

@ -1,23 +1,27 @@
.. _tags: .. _tags:
Tags Tool categories
==== ===============
This is the list of tags and their descriptions. Related DFHack tools are grouped by tags to make them easier to find. If you'd
like to see the full list of commands, please refer to the `index <genindex>`.
- adventure: Tools relevant to adventure mode These are the DFHack tool categories. Note that a tool may belong to more than
- fort: Tools relevant to fort mode one category.
- legends: Tools relevant to legends mode
- items: Tools that create or modify in-game items - :dfhack-tag:`adventure`: Tools relevant to adventure mode
- units: Tools that create or modify units - :dfhack-tag:`fort`: Tools relevant to fort mode
- jobs: Tools that create or modify jobs - :dfhack-tag:`legends`: Tools relevant to legends mode
- labors: Tools that deal with labor assignment - :dfhack-tag:`items`: Tools that create or modify in-game items
- auto: Tools that automatically manage some aspect of your fortress - :dfhack-tag:`units`: Tools that create or modify units
- map: Map modification - :dfhack-tag:`jobs`: Tools that create or modify jobs
- system: Tools related to working with DFHack commands or the core DFHack library - :dfhack-tag:`labors`: Tools that deal with labor assignment
- productivity: Tools that help you do things that you could do manually, but using the tool is better and faster - :dfhack-tag:`auto`: Tools that automatically manage some aspect of your fortress
- animals: Tools that help you manage animals - :dfhack-tag:`map`: Map modification
- fix: Tools that fix specific bugs - :dfhack-tag:`system`: Tools related to working with DFHack commands or the core DFHack library
- inspection: Tools that let you inspect game data - :dfhack-tag:`productivity`: Tools that help you do things that you could do manually, but using the tool is better and faster
- buildings/furniture: Tools that help you work wtih placing or configuring buildings and furniture - :dfhack-tag:`animals`: Tools that help you manage animals
- quickfort: Tools that are involved in creating and playing back blueprints - :dfhack-tag:`fix`: Tools that fix specific bugs
- :dfhack-tag:`inspection`: Tools that let you inspect game data
- :dfhack-tag:`buildings/furniture`: Tools that help you work wtih placing or configuring buildings and furniture
- :dfhack-tag:`quickfort`: Tools that are involved in creating and playing back blueprints

@ -1,15 +0,0 @@
.. _tools-index:
==================
DFHack Tools Index
==================
These pages contain information about the plugins, scripts, and built-in
commands distributed with DFHack.
.. toctree::
:titlesonly:
:glob:
/docs/tools/*
/docs/tools/*/*

@ -15,10 +15,9 @@ Quick Links
* `Downloads <https://www.github.com/DFHack/dfhack/releases>`_ * `Downloads <https://www.github.com/DFHack/dfhack/releases>`_
* `Installation guide <installing>` * `Installation guide <installing>`
* `Source code <https://www.github.com/DFHack/dfhack>`_ * `Getting help <support>`
(**important:** read `compile` before attempting to build from source) * :source:`Source code <>`
* `Bay 12 forums thread <https://dfhack.org/bay12>`_ (**important:** read `compile` before attempting to build from source.)
* `Bug tracker <https://www.github.com/DFHack/dfhack/issues>`_
User Manual User Manual
=========== ===========
@ -30,25 +29,7 @@ User Manual
/docs/Installing /docs/Installing
/docs/Support /docs/Support
/docs/Core /docs/Core
/docs/Tags
/docs/guides/index /docs/guides/index
/docs/index-about
/docs/index-dev /docs/index-dev
/docs/index-about
Tools
=====
DFHack commands, plugins, and scripts are grouped by tags to make it easier to
find groups of related tools.
.. note::
In order to avoid user confusion, as a matter of policy all GUI tools
display the word :guilabel:`DFHack` on the screen somewhere while active.
When that is not appropriate because they merely add keybinding hints to
existing DF screens, they deliberately use red instead of green for the key.
.. toctree::
:maxdepth: 1
/docs/Tags
/docs/index-tools