From 7acec133baf4e5c27e8235589f1f6cc465e19de4 Mon Sep 17 00:00:00 2001 From: myk002 Date: Mon, 15 Aug 2022 23:14:50 -0700 Subject: [PATCH] organize tags by group, add more info about tools --- conf.py | 39 ++++++++++++++++++++------------ docs/Categories.rst | 13 ----------- docs/Documentation.rst | 4 ++-- docs/Tags.rst | 19 ++++++++++++++++ docs/Tools.rst | 50 ++++++++++++++++++++++++++++++++++++++++++ index.rst | 2 +- 6 files changed, 97 insertions(+), 30 deletions(-) delete mode 100644 docs/Categories.rst create mode 100644 docs/Tools.rst diff --git a/conf.py b/conf.py index 0eaeb95f7..c71f69a4b 100644 --- a/conf.py +++ b/conf.py @@ -73,29 +73,40 @@ DOC_ALL_DIRS = doc_all_dirs() def get_tags(): - tags = [] + groups = {} + group_re = re.compile(r'"([^"]+)"') tag_re = re.compile(r'- `tag/([^`]+)`: (.*)') with open('docs/Tags.rst') as f: lines = f.readlines() for line in lines: - m = re.match(tag_re, line.strip()) + line = line.strip() + m = re.match(group_re, line) if m: - tags.append((m.group(1), m.group(2))) - return tags + group = m.group(1) + 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(): os.makedirs('docs/tags', mode=0o755, exist_ok=True) - with write_file_if_changed('docs/tags/index.rst') as topidx: - for tag_tuple in get_tags(): - tag = tag_tuple[0] - 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') - topidx.write(('.. _tag/{name}:\n\n').format(name=tag)) - topidx.write(('{name}\n').format(name=tag)) - topidx.write(('{underline}\n').format(underline='-'*len(tag))) - topidx.write(('{desc}\n\n').format(desc=tag_tuple[1])) - topidx.write(('.. include:: /docs/tags/{name}.rst\n\n').format(name=tag)) + tag_groups = 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] + 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') + topidx.write(('.. _tag/{name}:\n\n').format(name=tag)) + topidx.write(('{name}\n').format(name=tag)) + topidx.write(('{underline}\n').format(underline='*'*len(tag))) + topidx.write(('{desc}\n\n').format(desc=tag_tuple[1])) + topidx.write(('.. include:: /docs/tags/{name}.rst\n\n').format(name=tag)) def write_tool_docs(): diff --git a/docs/Categories.rst b/docs/Categories.rst deleted file mode 100644 index 46fc71bdf..000000000 --- a/docs/Categories.rst +++ /dev/null @@ -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 `. - -.. contents:: Contents - :local: - -.. include:: tags/index.rst diff --git a/docs/Documentation.rst b/docs/Documentation.rst index 8908272ca..07b2fa467 100644 --- a/docs/Documentation.rst +++ b/docs/Documentation.rst @@ -64,8 +64,8 @@ Tags 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 -commands, both in the HTML documents and in-game. See the list of available tags -`here ` and think about which categories your new tools belongs in. +commands, both in the HTML documents and in-game. See the list of available `tag-list` and +think about which categories your new tool belongs in. Links ----- diff --git a/docs/Tags.rst b/docs/Tags.rst index 96faf74e2..7f73bf799 100644 --- a/docs/Tags.rst +++ b/docs/Tags.rst @@ -1,10 +1,26 @@ :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/fort`: Tools that are useful while in fort 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/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/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. @@ -14,6 +30,9 @@ - `tag/fps`: Tools that help you manage FPS drop. - `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. + +"what" tags +----------- - `tag/animals`: Tools that interact with animals. - `tag/buildings`: Tools that interact with buildings and furniture. - `tag/stockpiles`: Tools that interact wtih stockpiles. diff --git a/docs/Tools.rst b/docs/Tools.rst new file mode 100644 index 000000000..623fc9c1f --- /dev/null +++ b/docs/Tools.rst @@ -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 `. + +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 diff --git a/index.rst b/index.rst index d627267f0..a54ea87f5 100644 --- a/index.rst +++ b/index.rst @@ -28,7 +28,7 @@ User Manual /docs/Introduction /docs/Installing /docs/Core - /docs/Categories + /docs/Tools /docs/guides/index /docs/index-dev /docs/index-about