organize tags by group, add more info about tools

develop
myk002 2022-08-15 23:14:50 -07:00
parent b01ef4a962
commit 7acec133ba
No known key found for this signature in database
GPG Key ID: 8A39CA0FA0C16E78
6 changed files with 97 additions and 30 deletions

@ -73,27 +73,38 @@ DOC_ALL_DIRS = doc_all_dirs()
def get_tags(): def get_tags():
tags = [] groups = {}
group_re = re.compile(r'"([^"]+)"')
tag_re = re.compile(r'- `tag/([^`]+)`: (.*)') tag_re = re.compile(r'- `tag/([^`]+)`: (.*)')
with open('docs/Tags.rst') as f: with open('docs/Tags.rst') as f:
lines = f.readlines() lines = f.readlines()
for line in lines: for line in lines:
m = re.match(tag_re, line.strip()) line = line.strip()
m = re.match(group_re, line)
if m: if m:
tags.append((m.group(1), m.group(2))) group = m.group(1)
return tags 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(): def generate_tag_indices():
os.makedirs('docs/tags', mode=0o755, exist_ok=True) os.makedirs('docs/tags', mode=0o755, exist_ok=True)
with write_file_if_changed('docs/tags/index.rst') as topidx: tag_groups = get_tags()
for tag_tuple in 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] tag = tag_tuple[0]
with write_file_if_changed(('docs/tags/{name}.rst').format(name=tag)) as tagidx: 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') tagidx.write('TODO: add links to the tools that have this tag')
topidx.write(('.. _tag/{name}:\n\n').format(name=tag)) topidx.write(('.. _tag/{name}:\n\n').format(name=tag))
topidx.write(('{name}\n').format(name=tag)) topidx.write(('{name}\n').format(name=tag))
topidx.write(('{underline}\n').format(underline='-'*len(tag))) topidx.write(('{underline}\n').format(underline='*'*len(tag)))
topidx.write(('{desc}\n\n').format(desc=tag_tuple[1])) topidx.write(('{desc}\n\n').format(desc=tag_tuple[1]))
topidx.write(('.. include:: /docs/tags/{name}.rst\n\n').format(name=tag)) topidx.write(('.. include:: /docs/tags/{name}.rst\n\n').format(name=tag))

@ -1,13 +0,0 @@
.. _categories:
Tool categories
===============
DFHack tools are grouped to make them easier to find. Note that a tool can
belong to more than one category. If you'd like to see the full list of tools
in one flat list, please refer to the `index <genindex>`.
.. contents:: Contents
:local:
.. include:: tags/index.rst

@ -64,8 +64,8 @@ Tags
To make it easier for players to find related commands, all plugins and commands are marked To make it easier for players to find related commands, all plugins and commands are marked
with relevant tags. These are used to compile indices and generate cross-links between the with relevant tags. These are used to compile indices and generate cross-links between the
commands, both in the HTML documents and in-game. See the list of available tags commands, both in the HTML documents and in-game. See the list of available `tag-list` and
`here <categories>` and think about which categories your new tools belongs in. think about which categories your new tool belongs in.
Links Links
----- -----

@ -1,10 +1,26 @@
:orphan: :orphan:
.. _tag-list:
DFHack tool tags
================
A tool often has at least one tag per group, encompassing when you use the tool,
why you might want to use it, and what kind of thing you're trying to affect.
See https://docs.google.com/spreadsheets/d/1hiDlo8M_bB_1jE-5HRs2RrrA_VZ4cRu9VXaTctX_nwk/edit#gid=1774645373
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/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/fort`: Tools that are useful while in fort mode. - `tag/fort`: Tools that are useful while in fort mode.
- `tag/legends`: Tools that are useful while in legends mode. - `tag/legends`: Tools that are useful while in legends mode.
- `tag/embark`: Tools that are useful while on the fort embark screen or while creating an adventurer. - `tag/embark`: Tools that are useful while on the fort embark screen or while creating an adventurer.
- `tag/dev`: Tools that are useful when developing scripts or mods. - `tag/dev`: Tools that are useful when developing scripts or mods.
"why" tags
----------
- `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/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/auto`: Tools that run in the background and automatically manage routine, toilsome aspects of your fortress. - `tag/auto`: Tools that run in the background and automatically manage routine, toilsome aspects of your fortress.
- `tag/productivity`: Tools that help you do things that you could do manually, but using the tool is better and faster. - `tag/productivity`: Tools that help you do things that you could do manually, but using the tool is better and faster.
@ -14,6 +30,9 @@
- `tag/fps`: Tools that help you manage FPS drop. - `tag/fps`: Tools that help you manage FPS drop.
- `tag/bugfix`: Tools that fix specific bugs, either permanently or on-demand. - `tag/bugfix`: Tools that fix specific bugs, either permanently or on-demand.
- `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/armok`: Tools that give you complete control over an aspect of the game or provide access to information that the game intentionally keeps hidden.
"what" tags
-----------
- `tag/animals`: Tools that interact with animals. - `tag/animals`: Tools that interact with animals.
- `tag/buildings`: Tools that interact with buildings and furniture. - `tag/buildings`: Tools that interact with buildings and furniture.
- `tag/stockpiles`: Tools that interact wtih stockpiles. - `tag/stockpiles`: Tools that interact wtih stockpiles.

@ -0,0 +1,50 @@
.. _tools:
DFHack tools
============
DFHack has **a lot** of tools. This page attempts to make it clearer what they
are, how they work, and how to find the ones you want.
.. contents:: Contents
:local:
What tools are and how they work
--------------------------------
DFHack is a Dwarf Fortress memory access and modification framework, so DFHack
tools normally access Dwarf Fortress internals and make some specific changes.
Some tools just make a targeted change when you run them, like `unforbid`, which
scans through all your items and removes the ``forbidden`` flag from each of
them.
Some tools need to be enabled, and then they run in the background and make
changes to the game on your behalf, like `autobutcher`, which monitors your
livestock population and automatically marks excess animals for butchering.
And some tools just exist to give you information that is otherwise hard to
come by, like `gui/petitions`, which shows you the active petitions for
guildhalls and temples that you have agreed to.
Finding the tool you need
-------------------------
DFHack tools are tagged with categories to make them easier to find. Note that a
tool can belong to more than one category. If you'd like to see the full list of
tools in one flat list, please refer to the `index <genindex>`.
DFHack tools by game mode
-------------------------
.. include:: tags/bywhen.rst
DFHack tools by theme
---------------------
.. include:: tags/bywhy.rst
DFHack tools by what they affect
--------------------------------
.. include:: tags/bywhat.rst

@ -28,7 +28,7 @@ User Manual
/docs/Introduction /docs/Introduction
/docs/Installing /docs/Installing
/docs/Core /docs/Core
/docs/Categories /docs/Tools
/docs/guides/index /docs/guides/index
/docs/index-dev /docs/index-dev
/docs/index-about /docs/index-about