From f9930b313aec99beac4257426f0ee969fccca681 Mon Sep 17 00:00:00 2001 From: myk002 Date: Tue, 9 Aug 2022 22:37:24 -0700 Subject: [PATCH] migrate all docs to the new directives add a summary option for tools and commands so we can output them with their tags and keybindings at the top of the file. --- docs/builtins/alias.rst | 16 ++--- docs/builtins/cls.rst | 15 +++-- docs/builtins/devel/dump-rpc.rst | 9 +-- docs/builtins/die.rst | 13 ++-- docs/builtins/disable.rst | 10 +-- docs/builtins/enable.rst | 16 ++--- docs/builtins/fpause.rst | 9 +-- docs/builtins/help.rst | 10 +-- docs/builtins/hide.rst | 12 ++-- docs/builtins/keybinding.rst | 13 ++-- docs/builtins/kill-lua.rst | 10 +-- docs/builtins/load.rst | 10 +-- docs/builtins/ls.rst | 7 +- docs/builtins/plug.rst | 17 +++-- docs/builtins/reload.rst | 11 ++-- docs/builtins/sc-script.rst | 12 ++-- docs/builtins/script.rst | 12 ++-- docs/builtins/show.rst | 14 ++-- docs/builtins/tags.rst | 11 ++-- docs/builtins/type.rst | 13 ++-- docs/builtins/unload.rst | 7 +- docs/plugins/3dveins.rst | 9 ++- docs/plugins/RemoteFortressReader.rst | 19 ++++-- docs/plugins/add-spatter.rst | 19 +++--- docs/plugins/autobutcher.rst | 13 ++-- docs/plugins/autochop.rst | 10 +-- docs/plugins/autoclothing.rst | 11 ++-- docs/plugins/autodump.rst | 20 +++--- docs/plugins/autofarm.rst | 16 ++--- docs/plugins/autogems.rst | 15 ++--- docs/plugins/autohauler.rst | 17 ++--- docs/plugins/autolabor.rst | 12 ++-- docs/plugins/automaterial.rst | 13 ++-- docs/plugins/automelt.rst | 9 ++- docs/plugins/autonestbox.rst | 25 +++++--- docs/plugins/autotrade.rst | 14 ++-- docs/plugins/blueprint.rst | 13 ++-- docs/plugins/building-hacks.rst | 6 +- docs/plugins/buildingplan.rst | 10 +-- docs/plugins/burrows.rst | 21 +++--- docs/plugins/changeitem.rst | 20 +++--- docs/plugins/changelayer.rst | 15 +++-- docs/plugins/changevein.rst | 14 ++-- docs/plugins/cleanconst.rst | 17 ++--- docs/plugins/cleaners.rst | 32 ++++++---- docs/plugins/cleanowned.rst | 17 ++--- docs/plugins/command-prompt.rst | 7 +- docs/plugins/confirm.rst | 12 ++-- docs/plugins/createitem.rst | 13 ++-- docs/plugins/cursecheck.rst | 7 +- docs/plugins/cxxrandom.rst | 6 +- docs/plugins/debug.rst | 14 ++-- docs/plugins/deramp.rst | 10 +-- docs/plugins/dig-now.rst | 16 ++--- docs/plugins/dig.rst | 71 ++++++++++++--------- docs/plugins/digFlood.rst | 19 +++--- docs/plugins/diggingInvaders.rst | 7 +- docs/plugins/dwarfmonitor.rst | 10 +-- docs/plugins/dwarfvet.rst | 7 +- docs/plugins/embark-assistant.rst | 17 ++--- docs/plugins/embark-tools.rst | 7 +- docs/plugins/eventful.rst | 6 +- docs/plugins/fastdwarf.rst | 6 +- docs/plugins/filltraffic.rst | 40 ++++++------ docs/plugins/fix-unit-occupancy.rst | 10 +-- docs/plugins/fixveins.rst | 10 +-- docs/plugins/flows.rst | 10 +-- docs/plugins/follow.rst | 12 ++-- docs/plugins/forceequip.rst | 17 ++--- docs/plugins/generated-creature-renamer.rst | 20 ++++-- docs/plugins/getplants.rst | 10 +-- docs/plugins/hotkeys.rst | 11 ++-- docs/plugins/infiniteSky.rst | 11 ++-- docs/plugins/isoworldremote.rst | 8 ++- docs/plugins/jobutils.rst | 18 ++++-- docs/plugins/labormanager.rst | 14 ++-- docs/plugins/lair.rst | 9 +-- docs/plugins/liquids.rst | 10 ++- docs/plugins/luasocket.rst | 6 +- docs/plugins/manipulator.rst | 9 ++- docs/plugins/map-render.rst | 6 +- docs/plugins/misery.rst | 6 +- docs/plugins/mode.rst | 6 +- docs/plugins/mousequery.rst | 6 +- docs/plugins/nestboxes.rst | 13 ++-- docs/plugins/orders.rst | 6 +- docs/plugins/pathable.rst | 10 +-- docs/plugins/petcapRemover.rst | 21 +++--- docs/plugins/plants.rst | 10 ++- docs/plugins/power-meter.rst | 12 ++-- docs/plugins/probe.rst | 14 ++-- docs/plugins/prospector.rst | 14 ++-- docs/plugins/regrass.rst | 11 ++-- docs/plugins/rename.rst | 8 ++- docs/plugins/rendermax.rst | 10 +-- docs/plugins/resume.rst | 21 +++--- docs/plugins/reveal.rst | 34 ++++++---- docs/plugins/ruby.rst | 15 +++-- docs/plugins/search.rst | 14 ++-- docs/plugins/seedwatch.rst | 6 +- docs/plugins/showmood.rst | 6 +- docs/plugins/siege-engine.rst | 11 ++-- docs/plugins/sort.rst | 14 ++-- docs/plugins/spectate.rst | 6 +- docs/plugins/steam-engine.rst | 11 ++-- docs/plugins/stockflow.rst | 12 ++-- docs/plugins/stockpiles.rst | 26 +++++--- docs/plugins/stocks.rst | 9 +-- docs/plugins/stonesense.rst | 10 +-- docs/plugins/strangemood.rst | 6 +- docs/plugins/tailor.rst | 17 ++--- docs/plugins/tiletypes.rst | 26 +++++--- docs/plugins/title-folder.rst | 6 +- docs/plugins/title-version.rst | 6 +- docs/plugins/trackstop.rst | 14 ++-- docs/plugins/tubefill.rst | 8 ++- docs/plugins/tweak.rst | 6 +- docs/plugins/workNow.rst | 12 ++-- docs/plugins/workflow.rst | 12 ++-- docs/plugins/xlsxreader.rst | 6 +- docs/plugins/zone.rst | 6 +- docs/sphinx_extensions/dfhack/tool_docs.py | 11 +++- 122 files changed, 913 insertions(+), 665 deletions(-) diff --git a/docs/builtins/alias.rst b/docs/builtins/alias.rst index 6efaf0776..84a761556 100644 --- a/docs/builtins/alias.rst +++ b/docs/builtins/alias.rst @@ -1,13 +1,13 @@ alias ===== -**Tags:** `tag/system` -:dfhack-keybind:`alias` - -:index:`Configure helper aliases for other DFHack commands. -` Aliases are -resolved immediately after built-in commands, which means that an alias cannot -override a built-in command, but can override a command implemented by a plugin -or script. + +.. dfhack-tool:: + :summary: Configure helper aliases for other DFHack commands. + :tags: system + +Aliases are resolved immediately after built-in commands, which means that an +alias cannot override a built-in command, but can override a command implemented +by a plugin or script. Usage: diff --git a/docs/builtins/cls.rst b/docs/builtins/cls.rst index d6a245081..2aad049b4 100644 --- a/docs/builtins/cls.rst +++ b/docs/builtins/cls.rst @@ -1,8 +1,13 @@ cls === -**Tags:** `tag/system` -:dfhack-keybind:`cls` -:index:`Clear the terminal screen. ` Can also -be invoked as ``clear``. Note that this command does not delete command history. -It just clears the text on the screen. +.. dfhack-tool:: + :summary: Clear the terminal screen. + :tags: system + +Can also be invoked as ``clear``. Note that this command does not delete command +history. It just clears the text on the screen. + +Usage:: + + cls diff --git a/docs/builtins/devel/dump-rpc.rst b/docs/builtins/devel/dump-rpc.rst index 65d4dae57..977b6e33c 100644 --- a/docs/builtins/devel/dump-rpc.rst +++ b/docs/builtins/devel/dump-rpc.rst @@ -1,10 +1,11 @@ devel/dump-rpc ============== -Tags: `tag/system` -:dfhack-keybind:`devel/dump-rpc` -:index:`Write RPC endpoint information to the specified file. -` +.. dfhack-tool:: + :summary: Dump RPC endpoint info. + :tags: dev + +Write RPC endpoint information to the specified file. Usage:: diff --git a/docs/builtins/die.rst b/docs/builtins/die.rst index db487da0e..b4873abc5 100644 --- a/docs/builtins/die.rst +++ b/docs/builtins/die.rst @@ -1,7 +1,12 @@ die === -**Tags:** `tag/system` -:dfhack-keybind:`die` -:index:`Instantly exit DF without saving. -` +.. dfhack-tool:: + :summary: Instantly exit DF without saving. + :tags: system + +Use to exit DF quickly and safely. + +Usage:: + + die diff --git a/docs/builtins/disable.rst b/docs/builtins/disable.rst index 758b6ff8f..e109e69e1 100644 --- a/docs/builtins/disable.rst +++ b/docs/builtins/disable.rst @@ -1,11 +1,11 @@ disable ======= -**Tags:** `tag/system` -:dfhack-keybind:`disable` -:index:`Deactivate a DFHack tool that has some persistent effect. -` See the -`enable` command for more info. +.. dfhack-tool:: + :summary: Deactivate a DFHack tool that has some persistent effect. + :tags: system + +See the `enable` command for more info. Usage:: diff --git a/docs/builtins/enable.rst b/docs/builtins/enable.rst index 8705bc4ef..63b0bdc5f 100644 --- a/docs/builtins/enable.rst +++ b/docs/builtins/enable.rst @@ -1,14 +1,14 @@ enable ====== -**Tags:** `tag/system` -:dfhack-keybind:`enable` -:index:`Activate a DFHack tool that has some persistent effect. -` Many plugins -and scripts can be in a distinct enabled or disabled state. Some of them -activate and deactivate automatically depending on the contents of the world -raws. Others store their state in world data. However a number of them have to -be enabled globally, and the init file is the right place to do it. +.. dfhack-tool:: + :summary: Activate a DFHack tool that has some persistent effect. + :tags: system + +Many plugins and scripts can be in a distinct enabled or disabled state. Some +of them activate and deactivate automatically depending on the contents of the +world raws. Others store their state in world data. However a number of them +have to be enabled globally, and the init file is the right place to do it. Most such plugins or scripts support the built-in ``enable`` and `disable` commands. Calling them at any time without arguments prints a list of enabled diff --git a/docs/builtins/fpause.rst b/docs/builtins/fpause.rst index beb783e82..2e8f851f7 100644 --- a/docs/builtins/fpause.rst +++ b/docs/builtins/fpause.rst @@ -1,10 +1,11 @@ fpause ====== -**Tags:** `tag/system` -:dfhack-keybind:`fpause` -:index:`Forces DF to pause. ` This is useful when -your FPS drops below 1 and you lose control of the game. +.. dfhack-tool:: + :summary: Forces DF to pause. + :tags: system + +This is useful when your FPS drops below 1 and you lose control of the game. Usage:: diff --git a/docs/builtins/help.rst b/docs/builtins/help.rst index 4195f2eaa..e1e913747 100644 --- a/docs/builtins/help.rst +++ b/docs/builtins/help.rst @@ -1,11 +1,11 @@ help ==== -**Tags:** `tag/system` -:dfhack-keybind:`help` -:index:`Display help about a command or plugin. -` Can also be invoked as ``?`` -or ``man`` (short for "manual"). +.. dfhack-tool:: + :summary: Display help about a command or plugin. + :tags: system + +Can also be invoked as ``?`` or ``man`` (short for "manual"). Usage:: diff --git a/docs/builtins/hide.rst b/docs/builtins/hide.rst index 087d87726..0ec8f36df 100644 --- a/docs/builtins/hide.rst +++ b/docs/builtins/hide.rst @@ -1,12 +1,12 @@ hide ==== -**Tags:** `tag/system` -:dfhack-keybind:`hide` -:index:`Hide the DFHack terminal window. -` You can show it again with the `show` -command, though you'll need to use it from a `keybinding` set beforehand or the -in-game `command-prompt`. +.. dfhack-tool:: + :summary: Hide the DFHack terminal window. + :tags: system + +You can show it again with the `show` command, though you'll need to use it from +a `keybinding` set beforehand or the in-game `command-prompt`. Only available on Windows. diff --git a/docs/builtins/keybinding.rst b/docs/builtins/keybinding.rst index fd857a42b..5ce8145f4 100644 --- a/docs/builtins/keybinding.rst +++ b/docs/builtins/keybinding.rst @@ -1,12 +1,13 @@ keybinding ========== -**Tags:** `tag/system` -:dfhack-keybind:`keybinding` -:index:`Create hotkeys that will run DFHack commands. -` Like any other -command, it can be used at any time from the console, but bindings are not -remembered between runs of the game unless re-created in `dfhack.init`. +.. dfhack-tool:: + :summary: Create hotkeys that will run DFHack commands. + :tags: system + +Like any other command, it can be used at any time from the console, but +bindings are not remembered between runs of the game unless re-created in +`dfhack.init`. Hotkeys can be any combinations of Ctrl/Alt/Shift with A-Z, 0-9, F1-F12, or ``\``` (the key below the ``Esc`` key. diff --git a/docs/builtins/kill-lua.rst b/docs/builtins/kill-lua.rst index 129268fa8..4de0ab7d1 100644 --- a/docs/builtins/kill-lua.rst +++ b/docs/builtins/kill-lua.rst @@ -1,11 +1,11 @@ kill-lua ======== -**Tags:** `tag/system` -:dfhack-keybind:`kill-lua` -:index:`Gracefully stops any currently-running Lua scripts. -` Use this -command to stop a misbehaving script that appears to be stuck. +.. dfhack-tool:: + :summary: Gracefully stop any currently-running Lua scripts. + :tags: system + +Use this command to stop a misbehaving script that appears to be stuck. Usage:: diff --git a/docs/builtins/load.rst b/docs/builtins/load.rst index cd3aed2c0..d253144a8 100644 --- a/docs/builtins/load.rst +++ b/docs/builtins/load.rst @@ -1,11 +1,11 @@ load ==== -**Tags:** `tag/system` -:dfhack-keybind:`load` -:index:`Load and register a plugin library. -` Also see `unload` and `reload` for -related actions. +.. dfhack-tool:: + :summary: Load and register a plugin library. + :tags: system + +Also see `unload` and `reload` for related actions. Usage:: diff --git a/docs/builtins/ls.rst b/docs/builtins/ls.rst index f03e3e533..702c8bae5 100644 --- a/docs/builtins/ls.rst +++ b/docs/builtins/ls.rst @@ -1,9 +1,10 @@ ls == -**Tags:** `tag/system` -:dfhack-keybind:`ls` -:index:`List available DFHack commands. ` +.. dfhack-tool:: + :summary: List available DFHack commands. + :tags: system + In order to group related commands, each command is associated with a list of tags. You can filter the listed commands by a tag or a substring of the command name. Can also be invoked as ``dir``. diff --git a/docs/builtins/plug.rst b/docs/builtins/plug.rst index 76e31c432..e10c154e5 100644 --- a/docs/builtins/plug.rst +++ b/docs/builtins/plug.rst @@ -1,14 +1,13 @@ plug ==== -**Tags:** `tag/system` -:dfhack-keybind:`plug` -:index:`List available plugins and whether they are enabled. -` +.. dfhack-tool:: + :summary: List available plugins and whether they are enabled. + :tags: system -Usage: +Usage:: -``plug`` - Lists available plugins and whether they are enabled. -``plug [ ...]`` - Lists only the named plugins. + plug [ [ ...]] + +If run with parameters, it lists only the named plugins. Otherwise it will list +all available plugins. diff --git a/docs/builtins/reload.rst b/docs/builtins/reload.rst index 8449c713d..1429e1038 100644 --- a/docs/builtins/reload.rst +++ b/docs/builtins/reload.rst @@ -1,11 +1,12 @@ reload ====== -**Tags:** `tag/system` -:dfhack-keybind:`reload` -:index:`Reload a loaded plugin. ` Developers -use this command to reload a plugin that they are actively modifying. Also see -`load` and `unload` for related actions. +.. dfhack-tool:: + :summary: Reload a loaded plugin. + :tags: system + +Developers use this command to reload a plugin that they are actively modifying. +Also see `load` and `unload` for related actions. Usage:: diff --git a/docs/builtins/sc-script.rst b/docs/builtins/sc-script.rst index 17c0efe25..b3255cb9f 100644 --- a/docs/builtins/sc-script.rst +++ b/docs/builtins/sc-script.rst @@ -1,12 +1,12 @@ sc-script ========= -**Tags:** `tag/system` -:dfhack-keybind:`sc-script` -:index:`Run commands when game state changes occur. -` This is similar to -the static `init-files` but is slightly more flexible since it can be set -dynamically. +.. dfhack-tool:: + :summary: Run commands when game state changes occur. + :tags: system + +This is similar to the static `init-files` but is slightly more flexible since +it can be set dynamically. Usage: diff --git a/docs/builtins/script.rst b/docs/builtins/script.rst index e5576ed50..fbcebff6c 100644 --- a/docs/builtins/script.rst +++ b/docs/builtins/script.rst @@ -1,12 +1,12 @@ script ====== -**Tags:** `tag/system` -:dfhack-keybind:`script` -:index:`Execute a batch file of DFHack commands. -` It reads a text file and -runs each line as a DFHack command as if it had been typed in by the user -- -treating the input like `an init file `. +.. dfhack-tool:: + :summary: Execute a batch file of DFHack commands. + :tags: system + +It reads a text file and runs each line as a DFHack command as if it had been +typed in by the user -- treating the input like `an init file `. Some other tools, such as `autobutcher` and `workflow`, export their settings as the commands to create them - which can later be reloaded with ``script``. diff --git a/docs/builtins/show.rst b/docs/builtins/show.rst index fde642726..7002d5aff 100644 --- a/docs/builtins/show.rst +++ b/docs/builtins/show.rst @@ -1,13 +1,13 @@ show ==== -**Tags:** `tag/system` -:dfhack-keybind:`show` -:index:`Unhides the DFHack terminal window. -` Useful if you have hidden the -terminal with `hide` and you want it back. Since the terminal window won't be -available to run this command, you'll need to use it from a `keybinding` set -beforehand or the in-game `command-prompt`. +.. dfhack-tool:: + :summary: Unhides the DFHack terminal window. + :tags: system + +Useful if you have hidden the terminal with `hide` and you want it back. Since +the terminal window won't be available to run this command, you'll need to use +it from a `keybinding` set beforehand or the in-game `command-prompt`. Only available on Windows. diff --git a/docs/builtins/tags.rst b/docs/builtins/tags.rst index 024677cff..93a094149 100644 --- a/docs/builtins/tags.rst +++ b/docs/builtins/tags.rst @@ -1,11 +1,12 @@ tags ==== -**Tags:** `tag/system` -:dfhack-keybind:`tags` -:index:`List the strings that DFHack tools can be tagged with. -` You can find -groups of related tools by passing the tag name to the `ls` command. +.. dfhack-tool:: + :summary: List the strings that DFHack tools can be tagged with. + :tags: system + +You can find groups of related tools by passing the tag name to the `ls` +command. Usage:: diff --git a/docs/builtins/type.rst b/docs/builtins/type.rst index d7cf9588e..3336cae5f 100644 --- a/docs/builtins/type.rst +++ b/docs/builtins/type.rst @@ -1,12 +1,13 @@ type ==== -**Tags:** `tag/system` -:dfhack-keybind:`type` -:index:`Describe how a command is implemented. -` DFHack commands can be provided -by plugins, scripts, or by the core library itself. The ``type`` command can -tell you which is the source of a particular command. +.. dfhack-tool:: + :summary: Describe how a command is implemented. + :tags: system + +DFHack commands can be provided by plugins, scripts, or by the core library +itself. The ``type`` command can tell you which is the source of a particular +command. Usage:: diff --git a/docs/builtins/unload.rst b/docs/builtins/unload.rst index e79d624ec..132732a7f 100644 --- a/docs/builtins/unload.rst +++ b/docs/builtins/unload.rst @@ -1,9 +1,10 @@ unload ====== -**Tags:** `tag/system` -:dfhack-keybind:`unload` -:index:`Unload a plugin from memory. ` +.. dfhack-tool:: + :summary: Unload a plugin from memory. + :tags: system + Also see `load` and `reload` for related actions. Usage:: diff --git a/docs/plugins/3dveins.rst b/docs/plugins/3dveins.rst index 63f6cfd8d..c60582310 100644 --- a/docs/plugins/3dveins.rst +++ b/docs/plugins/3dveins.rst @@ -2,13 +2,12 @@ ======= .. dfhack-tool:: + :summary: Rewrite layer veins to expand in 3D space. :tags: fort mod map -:index:`Rewrite layer veins to expand in 3D space. -<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 -their place. The transformation preserves the mineral counts reported by -`prospect`. +Existing, flat veins are removed and new 3D veins that naturally span z-levels +are generated in their place. The transformation preserves the mineral counts +reported by `prospect`. Usage:: diff --git a/docs/plugins/RemoteFortressReader.rst b/docs/plugins/RemoteFortressReader.rst index da8c3570e..f849266c2 100644 --- a/docs/plugins/RemoteFortressReader.rst +++ b/docs/plugins/RemoteFortressReader.rst @@ -1,12 +1,19 @@ RemoteFortressReader ==================== -**Tags:** `tag/dev` -:dfhack-keybind:`RemoteFortressReader_version` -:dfhack-keybind:`load-art-image-chunk` -:index:`Backend for Armok Vision. -` Provides an API for realtime -remote fortress visualization. See :forums:`Armok Vision <146473>`. +.. dfhack-tool:: + :summary: Backend for Armok Vision. + :tags: dev + :no-command: + +.. dfhack-command:: RemoteFortressReader_version + :summary: Print the loaded RemoteFortressReader version. + +.. dfhack-command:: load-art-image-chunk + :summary: Gets an art image chunk by index. + +This plugin provides an API for realtime remote fortress visualization. See +:forums:`Armok Vision <146473>`. Usage: diff --git a/docs/plugins/add-spatter.rst b/docs/plugins/add-spatter.rst index ed3675132..06739291e 100644 --- a/docs/plugins/add-spatter.rst +++ b/docs/plugins/add-spatter.rst @@ -1,11 +1,14 @@ add-spatter =========== -**Tags:** `tag/adventure`, `tag/fort`, `tag/mod`, `tag/items` -:index:`Make tagged reactions produce contaminants. -` Give some use to all -those poisons that can be bought from caravans! The plugin automatically enables -itself when you load a world with reactions that include names starting with -``SPATTER_ADD_``. These reactions will then produce contaminants on items -instead of improvements. The contaminants are immune to being washed away by -water or destroyed by `clean`. +.. dfhack-tool:: + :summary: Make tagged reactions produce contaminants. + :tags: adventure fort mod items + :no-command: + +Give some use to all those poisons that can be bought from caravans! The plugin +automatically enables itself when you load a world with reactions that include +names starting with ``SPATTER_ADD_``, so there are no commands to run to use it. +These reactions will then produce contaminants on items instead of improvements. +The contaminants are immune to being washed away by water or destroyed by +`clean`. diff --git a/docs/plugins/autobutcher.rst b/docs/plugins/autobutcher.rst index 7a960012e..9379ae9c1 100644 --- a/docs/plugins/autobutcher.rst +++ b/docs/plugins/autobutcher.rst @@ -1,12 +1,13 @@ autobutcher =========== -**Tags:** `tag/fort`, `tag/auto`, `tag/fps`, `tag/animals` -:dfhack-keybind:`autobutcher` -Automatically butcher excess livestock. This plugin monitors how many pets you -have of each gender and age and assigns excess lifestock for slaughter. Requires -that you add the target race(s) to a watch list. Units will be ignored if they -are: +.. dfhack-tool:: + :summary: Automatically butcher excess livestock. + :tags: fort auto fps animals + +This plugin monitors how many pets you have of each gender and age and assigns +excess lifestock for slaughter. It requires that you add the target race(s) to a +watch list. Units will be ignored if they are: * Untamed * Nicknamed (for custom protection; you can use the `rename` ``unit`` tool diff --git a/docs/plugins/autochop.rst b/docs/plugins/autochop.rst index 6b0b7125e..b445384fb 100644 --- a/docs/plugins/autochop.rst +++ b/docs/plugins/autochop.rst @@ -1,10 +1,12 @@ autochop ======== -**Tags:** `tag/fort`, `tag/auto` -:index:`Auto-harvest trees when low on stockpiled logs. -` This plugin can -designate trees for chopping when your stocks are low on logs. +.. dfhack-tool:: + :summary: Auto-harvest trees when low on stockpiled logs. + :tags: fort auto + :no-command: + +This plugin can designate trees for chopping when your stocks are low on logs. Usage:: diff --git a/docs/plugins/autoclothing.rst b/docs/plugins/autoclothing.rst index 3feb22520..a5b57dfb1 100644 --- a/docs/plugins/autoclothing.rst +++ b/docs/plugins/autoclothing.rst @@ -1,11 +1,12 @@ autoclothing ============ -**Tags:** `tag/fort`, `tag/auto`, `tag/jobs` -:dfhack-keybind:`autoclothing` -:index:`Automatically manage clothing work orders. -` It allows you to -set how many of each clothing type every citizen should have. +.. dfhack-tool:: + :summary: Automatically manage clothing work orders. + :tags: fort auto jobs + +This command allows you to set how many of each clothing type every citizen +should have. Usage:: diff --git a/docs/plugins/autodump.rst b/docs/plugins/autodump.rst index 3e8d291a0..0fd7ee23c 100644 --- a/docs/plugins/autodump.rst +++ b/docs/plugins/autodump.rst @@ -2,15 +2,20 @@ autodump ======== .. dfhack-tool:: + :summary: Automatically set items in a stockpile to be dumped. :tags: fort auto fps items stockpiles + :no-command: + +.. dfhack-command:: autodump + :summary: Teleports items marked for dumping to the cursor position. .. dfhack-command:: autodump-destroy-here + :summary: Destroy items marked for dumping under the cursor. .. dfhack-command:: autodump-destroy-item + :summary: Destroys the selected item. -:index:`Automatically set items in a stockpile to be dumped. -` When -`enabled `, this plugin adds an option to the :kbd:`q` menu for +When `enabled `, this plugin adds an option to the :kbd:`q` menu for stockpiles. When the ``autodump`` option is selected for the stockpile, any items placed in the stockpile will automatically be designated to be dumped. @@ -44,8 +49,7 @@ Options called again with this option before the game is resumed, it cancels pending destroy actions. ``destroy-here`` - :index:`Destroy items marked for dumping under the cursor. - ` + Destroy items marked for dumping under the cursor. ``visible`` Only process items that are not hidden. ``hidden`` @@ -57,10 +61,8 @@ Examples -------- ``autodump`` - :index:`Teleports items marked for dumping to the cursor position. - ` + Teleports items marked for dumping to the cursor position. ``autodump destroy`` Destroys all unforbidden items marked for dumping ``autodump-destroy-item`` - :index:`Destroys the selected item. - ` + Destroys the selected item. diff --git a/docs/plugins/autofarm.rst b/docs/plugins/autofarm.rst index bfe8ad717..44077eb89 100644 --- a/docs/plugins/autofarm.rst +++ b/docs/plugins/autofarm.rst @@ -1,13 +1,13 @@ autofarm ======== -**Tags:** `tag/fort`, `tag/auto`, `tag/buildings` -:dfhack-keybind:`autofarm` - -:index:`Automatically manage farm crop selection. -` This plugin periodically -scans your plant stocks and assigns crops to your farm plots based on which -plant stocks are low (as long as you have the appropriate seeds). The target -threshold for each crop type is configurable. + +.. dfhack-tool:: + :summary: Automatically manage farm crop selection. + :tags: fort auto buildings + +Periodically scan your plant stocks and assign crops to your farm plots based on +which plant stocks are low (as long as you have the appropriate seeds). The +target threshold for each crop type is configurable. Usage: diff --git a/docs/plugins/autogems.rst b/docs/plugins/autogems.rst index 11575aa7a..f95d74fea 100644 --- a/docs/plugins/autogems.rst +++ b/docs/plugins/autogems.rst @@ -1,15 +1,16 @@ autogems ======== -.. dfhack-tool:: autogems +.. dfhack-tool:: + :summary: Automatically cut rough gems. :tags: fort auto jobs :no-command: .. dfhack-command:: autogems-reload + :summary: Reloads the autogems configuration file. -:index:`Automatically cut rough gems. ` -This plugin periodically scans your stocks of rough gems and creates manager -orders for cutting them at a Jeweler's Workshop. +Automatically cut rough gems. This plugin periodically scans your stocks of +rough gems and creates manager orders for cutting them at a Jeweler's Workshop. Usage: @@ -17,10 +18,8 @@ Usage: Enables the plugin and starts autocutting gems according to its configuration. ``autogems-reload`` - :index:`Reloads the autogems configuration file. - ` You might need - to do this if you have manually modified the contents while the game is - running. + Reloads the autogems configuration file. You might need to do this if you + have manually modified the contents while the game is running. Run `gui/autogems` for a configuration UI, or access the ``Auto Cut Gems`` option from the Current Workshop Orders screen (:kbd:`o`-:kbd:`W`). diff --git a/docs/plugins/autohauler.rst b/docs/plugins/autohauler.rst index e0e1b2bac..1a4a96c8f 100644 --- a/docs/plugins/autohauler.rst +++ b/docs/plugins/autohauler.rst @@ -1,13 +1,14 @@ autohauler ========== -**Tags:** `tag/fort`, `tag/auto`, `tag/labors` -:dfhack-keybind:`autohauler` - -:index:`Automatically manage hauling labors. -` Similar to `autolabor`, but -instead of managing all labors, ``autohauler`` only addresses hauling labors, -leaving the assignment of skilled labors entirely up to you. You can use the -in-game `manipulator` UI or an external tool like Dwarf Therapist to do so. + +.. dfhack-tool:: + :summary: Automatically manage hauling labors. + :tags: fort auto labors + +Similar to `autolabor`, but instead of managing all labors, ``autohauler`` only +addresses hauling labors, leaving the assignment of skilled labors entirely up +to you. You can use the in-game `manipulator` UI or an external tool like Dwarf +Therapist to do so. Idle dwarves who are not on active military duty will be assigned the hauling labors; everyone else (including those currently hauling) will have the hauling diff --git a/docs/plugins/autolabor.rst b/docs/plugins/autolabor.rst index 1d02fcfe8..d2fe49e87 100644 --- a/docs/plugins/autolabor.rst +++ b/docs/plugins/autolabor.rst @@ -1,12 +1,12 @@ autolabor ========= -**Tags:** `tag/fort`, `tag/auto`, `tag/labors` -:dfhack-keybind:`autolabor` -:index:`Automatically manage dwarf labors. -` Autolabor attempts to keep as -many dwarves as possible busy while allowing dwarves to specialize in specific -skills. +.. dfhack-tool:: + :summary: Automatically manage dwarf labors. + :tags: fort auto labors + +Autolabor attempts to keep as many dwarves as possible busy while allowing +dwarves to specialize in specific skills. Autolabor frequently checks how many jobs of each type are available and sets labors proportionally in order to get them all done quickly. Labors with diff --git a/docs/plugins/automaterial.rst b/docs/plugins/automaterial.rst index 1c237f260..513a963d2 100644 --- a/docs/plugins/automaterial.rst +++ b/docs/plugins/automaterial.rst @@ -1,11 +1,14 @@ automaterial ============ -**Tags:** `tag/fort`, `tag/productivity`, `tag/design`, `tag/buildings`, `tag/map` -:index:`Sorts building materials by recent usage. -` This makes building -constructions (walls, floors, fortifications, etc) much easier by saving you -from having to trawl through long lists of materials each time you place one. +.. dfhack-tool:: + :summary: Sorts building materials by recent usage. + :tags: fort productivity design buildings map + :no-command: + +This plugin makes building constructions (walls, floors, fortifications, etc) +much easier by saving you from having to trawl through long lists of materials +each time you place one. It moves the last used material for a given construction type to the top of the list, if there are any left. So if you build a wall with chalk blocks, the next diff --git a/docs/plugins/automelt.rst b/docs/plugins/automelt.rst index 6c42cbb7e..508fdaeaf 100644 --- a/docs/plugins/automelt.rst +++ b/docs/plugins/automelt.rst @@ -2,14 +2,13 @@ automelt ======== .. dfhack-tool:: + :summary: Quickly designate items to be melted. :tags: fort auto items stockpiles :no-command: -:index:`Quickly designate items to be melted. -` When `enabled `, this -plugin adds an option to the :kbd:`q` menu for stockpiles. When the ``automelt`` -option is selected for the stockpile, any items placed in the stockpile will -automatically be designated to be melted. +When `enabled `, this plugin adds an option to the :kbd:`q` menu for +stockpiles. When the ``automelt`` option is selected for the stockpile, any +items placed in the stockpile will automatically be designated to be melted. Usage:: diff --git a/docs/plugins/autonestbox.rst b/docs/plugins/autonestbox.rst index 2f874c452..b82a1a207 100644 --- a/docs/plugins/autonestbox.rst +++ b/docs/plugins/autonestbox.rst @@ -1,16 +1,21 @@ autonestbox =========== -**Tags:** `tag/fort`, `tag/auto`, `tag/animals` -:dfhack-keybind:`autonestbox` -Auto-assign egg-laying female pets to nestbox zones. Requires that you create -pen/pasture zones above nestboxes. If the pen is bigger than 1x1, the nestbox -must be in the top left corner. Only 1 unit will be assigned per pen, regardless -of the size. The age of the units is currently not checked since most birds grow -up quite fast. Egg layers who are also grazers will be ignored, since confining -them to a 1x1 pasture is not a good idea. Only tame and domesticated own units -are processed since pasturing half-trained wild egg layers could destroy your -neat nestbox zones when they revert to wild. +.. dfhack-tool:: + :summary: Auto-assign egg-laying female pets to nestbox zones. + :tags: fort auto animals + +To use this feature, you must create pen/pasture zones above nestboxes. If the +pen is bigger than 1x1, the nestbox must be in the top left corner. Only 1 unit +will be assigned per pen, regardless of the size. Egg layers who are also +grazers will be ignored, since confining them to a 1x1 pasture is not a good +idea. Only tame and domesticated own units are processed since pasturing +half-trained wild egg layers could destroy your neat nestbox zones when they +revert to wild. + +Note that the age of the units is not checked, so you might get some egg-laying +kids assigned to the nestbox zones. Most birds grow up quite fast, though, so +they should be adults and laying eggs soon enough. Usage: diff --git a/docs/plugins/autotrade.rst b/docs/plugins/autotrade.rst index 35657fc88..f27fab122 100644 --- a/docs/plugins/autotrade.rst +++ b/docs/plugins/autotrade.rst @@ -1,12 +1,14 @@ autotrade ========= -**Tags:** `tag/fort`, `tag/auto`, `tag/items`, `tag/stockpiles` -:index:`Quickly designate items to be traded. -` When `enabled `, -this plugin adds an option to the :kbd:`q` menu for stockpiles. When the -``autotrade`` option is selected for the stockpile, any items placed in the -stockpile will automatically be designated to be traded. +.. dfhack-tool:: + :summary: Quickly designate items to be traded. + :tags: fort auto items stockpiles + :no-command: + +When `enabled `, this plugin adds an option to the :kbd:`q` menu for +stockpiles. When the ``autotrade`` option is selected for the stockpile, any +items placed in the stockpile will automatically be designated to be traded. Usage:: diff --git a/docs/plugins/blueprint.rst b/docs/plugins/blueprint.rst index 48ffdd883..8654aa1ec 100644 --- a/docs/plugins/blueprint.rst +++ b/docs/plugins/blueprint.rst @@ -1,12 +1,13 @@ blueprint ========= -**Tags:** `tag/fort`, `tag/design`, `tag/quickfort`, `tag/map` -:dfhack-keybind:`blueprint` -:index:`Record a live game map in a quickfort blueprint. -` With -``blueprint``, you can export the structure of a portion of your fortress in a -blueprint file that you (or anyone else) can later play back with `quickfort`. +.. dfhack-tool:: + :summary: Record a live game map in a quickfort blueprint. + :tags: fort design quickfort map + +With ``blueprint``, you can export the structure of a portion of your fortress +in a blueprint file that you (or anyone else) can later play back with +`quickfort`. Blueprints are ``.csv`` or ``.xlsx`` files created in the ``blueprints`` subdirectory of your DF folder. The map area to turn into a blueprint is either diff --git a/docs/plugins/building-hacks.rst b/docs/plugins/building-hacks.rst index 1f8ee1b2b..cd8835f37 100644 --- a/docs/plugins/building-hacks.rst +++ b/docs/plugins/building-hacks.rst @@ -1,7 +1,9 @@ building-hacks ============== -**Tags:** `tag/fort`, `tag/mod`, `tag/buildings` -Provides a Lua API for creating powered workshops. +.. dfhack-tool:: + :summary: Provides a Lua API for creating powered workshops. + :tags: fort mod buildings + :no-command: See `building-hacks-api` for more details. diff --git a/docs/plugins/buildingplan.rst b/docs/plugins/buildingplan.rst index be95dc6f1..ea9d78f64 100644 --- a/docs/plugins/buildingplan.rst +++ b/docs/plugins/buildingplan.rst @@ -1,11 +1,11 @@ buildingplan ============ -**Tags:** `tag/fort`, `tag/design`, `tag/quickfort`, `tag/buildings`, `tag/map` -:dfhack-keybind:`buildingplan` -:index:`Plan building construction before you have materials. -` This -plugin adds a planning mode for building placement. You can then place +.. dfhack-tool:: + :summary: Plan building construction before you have materials. + :tags: fort design quickfort buildings map + +This plugin adds a planning mode for building placement. You can then place furniture, constructions, and other buildings before the required materials are available, and they will be created in a suspended state. Buildingplan will periodically scan for appropriate items, and the jobs will be unsuspended when diff --git a/docs/plugins/burrows.rst b/docs/plugins/burrows.rst index 4728e2cd5..92e62f08b 100644 --- a/docs/plugins/burrows.rst +++ b/docs/plugins/burrows.rst @@ -1,24 +1,23 @@ burrows ======= -**Tags:** `tag/fort`, `tag/auto`, `tag/productivity`, `tag/units` -:dfhack-keybind:`burrow` -:index:`Auto-expand burrows as you dig. -` When a wall inside a burrow -with a name ending in ``+`` is dug out, the burrow will be extended to -newly-revealed adjacent walls. Note that digging 1-wide corridors with the miner -inside the burrow is **SLOW**. +.. dfhack-tool:: + :summary: Auto-expand burrows as you dig. + :tags: fort auto productivity units + :no-command: -You can also use the ``burrow`` command to -:index:`quickly add units/tiles to burrows. -` +.. dfhack-command:: burrow + :summary: Quickly add units/tiles to burrows. + +When a wall inside a burrow with a name ending in ``+`` is dug out, the burrow +will be extended to newly-revealed adjacent walls. Usage: ``burrow enable auto-grow`` When a wall inside a burrow with a name ending in '+' is dug out, the burrow will be extended to newly-revealed adjacent walls. This final '+' may be - omitted in burrow name args of other ``burrows`` commands. Note that digging + omitted in burrow name args of other ``burrow`` commands. Note that digging 1-wide corridors with the miner inside the burrow is SLOW. ``burrow disable auto-grow`` Disables auto-grow processing. diff --git a/docs/plugins/changeitem.rst b/docs/plugins/changeitem.rst index 68c53f821..e49698822 100644 --- a/docs/plugins/changeitem.rst +++ b/docs/plugins/changeitem.rst @@ -1,15 +1,15 @@ changeitem ========== -**Tags:** `tag/adventure`, `tag/fort`, `tag/armok`, `tag/items` -:dfhack-keybind:`changeitem` - -:index:`Change item material and base quality. -` By default, a change is -only allowed if the existing and desired item materials are of the same subtype -(for example wood -> wood, stone -> stone, etc). But since some transformations -work pretty well and may be desired you can override this with ``force``. Note -that forced changes can possibly result in items that crafters and haulers -refuse to touch. + +.. dfhack-tool:: + :summary: Change item material or base quality. + :tags: adventure fort armok items + +By default, a change is only allowed if the existing and desired item materials +are of the same subtype (for example wood -> wood, stone -> stone, etc). But +since some transformations work pretty well and may be desired you can override +this with ``force``. Note that forced changes can possibly result in items that +crafters and haulers refuse to touch. Usage: diff --git a/docs/plugins/changelayer.rst b/docs/plugins/changelayer.rst index 1267fbdac..e44d6f317 100644 --- a/docs/plugins/changelayer.rst +++ b/docs/plugins/changelayer.rst @@ -1,13 +1,14 @@ changelayer =========== -**Tags:** `tag/fort`, `tag/armok`, `tag/map` -:dfhack-keybind:`changelayer` -:index:`Change the material of an entire geology layer. -` Note that one -layer can stretch across many z-levels, and changes to the geology layer will -affect all surrounding regions, not just your embark! Mineral veins and gem -clusters will not be affected. Use `changevein` if you want to modify those. +.. dfhack-tool:: + :summary: Change the material of an entire geology layer. + :tags: fort armok map + +Note that one layer can stretch across many z-levels, and changes to the geology +layer will affect all surrounding regions, not just your embark! Mineral veins +and gem clusters will not be affected. Use `changevein` if you want to modify +those. tl;dr: You will end up with changing large areas in one go, especially if you use it in lower z levels. Use this command with care! diff --git a/docs/plugins/changevein.rst b/docs/plugins/changevein.rst index 96c68de76..4811c416c 100644 --- a/docs/plugins/changevein.rst +++ b/docs/plugins/changevein.rst @@ -1,13 +1,13 @@ changevein ========== -**Tags:** `tag/fort`, `tag/armok`, `tag/map` -:dfhack-keybind:`changevein` -:index:`Change the material of a mineral inclusion. -` You can change it to -any incorganic material RAW id. Note that this command only affects tiles within -the current 16x16 block - for large veins and clusters, you will need to use -this command multiple times. +.. dfhack-tool:: + :summary: Change the material of a mineral inclusion. + :tags: fort armok map + +You can change a vein to any incorganic material RAW id. Note that this command +only affects tiles within the current 16x16 block - for large veins and +clusters, you will need to use this command multiple times. You can use the `probe` command to discover the material RAW ids for existing veins that you want to duplicate. diff --git a/docs/plugins/cleanconst.rst b/docs/plugins/cleanconst.rst index c47a8c6dd..9c0309105 100644 --- a/docs/plugins/cleanconst.rst +++ b/docs/plugins/cleanconst.rst @@ -1,13 +1,14 @@ cleanconst ========== -**Tags:** `tag/fort`, `tag/fps`, `tag/map` -:dfhack-keybind:`cleanconst` - -:index:`Cleans up construction materials. -` This tool alters all -constructions on the map so that they spawn their building component when they -are disassembled, allowing their actual build items to be safely deleted. This -can improve FPS when you have many constructions on the map. + +.. dfhack-tool:: + :summary: Cleans up construction materials. + :tags: fort fps map + +This tool alters all constructions on the map so that they spawn their building +component when they are disassembled, allowing their actual build items to be +safely deleted. This can improve FPS when you have many constructions on the +map. Usage:: diff --git a/docs/plugins/cleaners.rst b/docs/plugins/cleaners.rst index 20fa792db..42e585da1 100644 --- a/docs/plugins/cleaners.rst +++ b/docs/plugins/cleaners.rst @@ -3,15 +3,22 @@ cleaners ======== -**Tags:** `tag/adventure`, `tag/fort`, `tag/fps`, `tag/items`, `tag/map`, `tag/units` -:dfhack-keybind:`clean` -:dfhack-keybind:`spotclean` -:index:`Removes contaminants. ` More -specifically, it cleans all the splatter that get scattered all over the map and -that clings to your items and units. In an old fortress, cleaning with this tool -can significantly reduce FPS lag. It can also spoil your !!FUN!!, so think -before you use it. +.. dfhack-tool:: + :summary: Provides commands for cleaning spatter from the map. + :tags: adventure fort fps items map units + :no-command: + +.. dfhack-command:: clean + :summary: Removes contaminants. + +.. dfhack-command:: spotclean + :summary: Remove all contaminants from the tile under the cursor. + +This plugin provides commands that clean the splatter that get scattered all +over the map and that clings to your items and units. In an old fortress, +cleaning with this tool can significantly reduce FPS lag! It can also spoil your +!!FUN!!, so think before you use it. Usage:: @@ -21,11 +28,10 @@ Usage:: By default, cleaning the map leaves mud and snow alone. Note that cleaning units includes hostiles, and that cleaning items removes poisons from weapons. -``spotclean`` works like ``clean map snow mud``, -:index:`removing all contaminants from the tile under the cursor. -` This is ideal -if you just want to clean a specific tile but don't want the `clean` command to -remove all the glorious blood from your entranceway. +``spotclean`` works like ``clean map snow mud``, removing all contaminants from +the tile under the cursor. This is ideal if you just want to clean a specific +tile but don't want the `clean` command to remove all the glorious blood from +your entranceway. Examples -------- diff --git a/docs/plugins/cleanowned.rst b/docs/plugins/cleanowned.rst index 409c39345..7271ce402 100644 --- a/docs/plugins/cleanowned.rst +++ b/docs/plugins/cleanowned.rst @@ -1,13 +1,14 @@ cleanowned ========== -**Tags:** `tag/fort`, `tag/productivity`, `tag/items` -:dfhack-keybind:`cleanowned` - -:index:`Confiscates and dumps garbage owned by dwarves. -` This tool gets -dwarves to give up ownership of scattered items and items with heavy wear and -then marks those items for dumping. Now you can finally get your dwarves to give -up their rotten food and tattered loincloths and go get new ones! + +.. dfhack-tool:: + :summary: Confiscates and dumps garbage owned by dwarves. + :tags: fort productivity items + +This tool gets dwarves to give up ownership of scattered items and items with +heavy wear and then marks those items for dumping. Now you can finally get your +dwarves to give up their rotten food and tattered loincloths and go get new +ones! Usage:: diff --git a/docs/plugins/command-prompt.rst b/docs/plugins/command-prompt.rst index 312734b97..278741f36 100644 --- a/docs/plugins/command-prompt.rst +++ b/docs/plugins/command-prompt.rst @@ -1,10 +1,9 @@ command-prompt ============== -**Tags:** `tag/system` -:dfhack-keybind:`command-prompt` -:index:`An in-game DFHack terminal where you can enter other commands. -` +.. dfhack-tool:: + :summary: An in-game DFHack terminal where you can run other commands. + :tags: system Usage:: diff --git a/docs/plugins/confirm.rst b/docs/plugins/confirm.rst index de2556b6f..aef18c9c0 100644 --- a/docs/plugins/confirm.rst +++ b/docs/plugins/confirm.rst @@ -1,12 +1,12 @@ confirm ======= -**Tags:** `tag/fort`, `tag/interface` -:dfhack-keybind:`confirm` -:index:`Adds confirmation dialogs for destructive actions. -` Now you can get -the chance to avoid seizing goods from traders or deleting a hauling route in -case you hit the key accidentally. +.. dfhack-tool:: + :summary: Adds confirmation dialogs for destructive actions. + :tags: fort interface + +Now you can get the chance to avoid seizing goods from traders or deleting a +hauling route in case you hit the key accidentally. Usage: diff --git a/docs/plugins/createitem.rst b/docs/plugins/createitem.rst index 38f072e62..dfd286395 100644 --- a/docs/plugins/createitem.rst +++ b/docs/plugins/createitem.rst @@ -1,12 +1,13 @@ createitem ========== -**Tags:** `tag/adventure`, `tag/fort`, `tag/armok`, `tag/items` -:dfhack-keybind:`createitem` -:index:`Create arbitrary items. ` You can -create new items of any type and made of any material. A unit must be selected -in-game to use this command. By default, items created are spawned at the feet -of the selected unit. +.. dfhack-tool:: + :summary: Create arbitrary items. + :tags: adventure fort armok items + +You can create new items of any type and made of any material. A unit must be +selected in-game to use this command. By default, items created are spawned at +the feet of the selected unit. Specify the item and material information as you would indicate them in custom reaction raws, with the following differences: diff --git a/docs/plugins/cursecheck.rst b/docs/plugins/cursecheck.rst index ecb4dbd2f..b2e2943ba 100644 --- a/docs/plugins/cursecheck.rst +++ b/docs/plugins/cursecheck.rst @@ -1,9 +1,10 @@ cursecheck ========== -**Tags:** `tag/system`, `tag/interface` -:dfhack-keybind:`cursecheck` -:index:`Check for cursed creatures. ` +.. dfhack-tool:: + :summary: Check for cursed creatures. + :tags: system interface + This command checks a single map tile (or the whole map/world) for cursed creatures (ghosts, vampires, necromancers, werebeasts, zombies, etc.). diff --git a/docs/plugins/cxxrandom.rst b/docs/plugins/cxxrandom.rst index 0016fb8d0..19788e4a4 100644 --- a/docs/plugins/cxxrandom.rst +++ b/docs/plugins/cxxrandom.rst @@ -1,7 +1,9 @@ cxxrandom ========= -**Tags:** `tag/dev` -Provides a Lua API for random distributions. +.. dfhack-tool:: + :summary: Provides a Lua API for random distributions. + :tags: dev + :no-command: See `cxxrandom-api` for details. diff --git a/docs/plugins/debug.rst b/docs/plugins/debug.rst index 4cc94b217..a9e601c77 100644 --- a/docs/plugins/debug.rst +++ b/docs/plugins/debug.rst @@ -1,11 +1,15 @@ debug ===== -**Tags:** `tag/dev` -:dfhack-keybind:`debugfilter` -:index:`Configure verbosity of DFHack debug output. -` Debug output is -grouped by plugin name, category name, and verbosity level. +.. dfhack-tool:: + :summary: Provides commands for controlling debug log verbosity. + :tags: dev + :no-command: + +.. dfhack-command:: debugfilter + :summary: Configure verbosity of DFHack debug output. + +Debug output is grouped by plugin name, category name, and verbosity level. The verbosity levels are: diff --git a/docs/plugins/deramp.rst b/docs/plugins/deramp.rst index 6126d2828..4bb96ef0a 100644 --- a/docs/plugins/deramp.rst +++ b/docs/plugins/deramp.rst @@ -1,11 +1,11 @@ deramp ====== -**Tags:** `tag/fort`, `tag/armok`, `tag/map` -:dfhack-keybind:`deramp` -:index:`Removes all ramps designated for removal from the map. -` It also -removes any "floating" down ramps that can remain after a cave-in. +.. dfhack-tool:: + :summary: Removes all ramps designated for removal from the map. + :tags: fort armok map + +It also removes any "floating" down ramps that can remain after a cave-in. Usage:: diff --git a/docs/plugins/dig-now.rst b/docs/plugins/dig-now.rst index 7d3beedc0..0562e000a 100644 --- a/docs/plugins/dig-now.rst +++ b/docs/plugins/dig-now.rst @@ -1,14 +1,14 @@ dig-now ======= -**Tags:** `tag/fort`, `tag/armok`, `tag/map` -:dfhack-keybind:`dig-now` -:index:`Instantly complete dig designations. -` This tool will magically -complete non-marker dig designations, modifying tile shapes and creating -boulders, ores, and gems as if a miner were doing the mining or engraving. By -default, the entire map is processed and boulder generation follows standard -game rules, but the behavior is configurable. +.. dfhack-tool:: + :summary: Instantly complete dig designations. + :tags: fort armok map + +This tool will magically complete non-marker dig designations, modifying tile +shapes and creating boulders, ores, and gems as if a miner were doing the mining +or engraving. By default, the entire map is processed and boulder generation +follows standard game rules, but the behavior is configurable. Note that no units will get mining or engraving experience for the dug/engraved tiles. diff --git a/docs/plugins/dig.rst b/docs/plugins/dig.rst index f4e0c8acb..1761b7085 100644 --- a/docs/plugins/dig.rst +++ b/docs/plugins/dig.rst @@ -3,47 +3,58 @@ dig === -**Tags:** `tag/fort`, `tag/productivity`, `tag/design`, `tag/map` -:dfhack-keybind:`digv` -:dfhack-keybind:`digvx` -:dfhack-keybind:`digl` -:dfhack-keybind:`diglx` -:dfhack-keybind:`digcircle` -:dfhack-keybind:`digtype` -:dfhack-keybind:`digexp` -Make complicated dig patterns easy. +.. dfhack-tool:: + :summary: Provides commands for designating tiles for digging. + :tags: fort productivity design map + :no-command: + +.. dfhack-command:: digv + :summary: Designate all of the selected vein for digging. + +.. dfhack-command:: digvx + :summary: Dig a vein across z-levels, digging stairs as needed. + +.. dfhack-command:: digl + :summary: Dig all of the selected layer stone. + +.. dfhack-command:: diglx + :summary: Dig layer stone across z-levels, digging stairs as needed. + +.. dfhack-command:: digcircle + :summary: Designate circles. + +.. dfhack-command:: digtype + :summary: Designate all vein tiles of the selected type. + +.. dfhack-command:: digexp + :summary: Designate dig patterns for exploratory mining. + +This plugin provides commands to make complicated dig patterns easy. Usage: ``digv [x] [-p]`` - :index:`Designate all of the selected vein for digging. - ` + Designate all of the selected vein for digging. ``digvx [-p]`` - :index:`Dig a vein across z-levels, digging stairs as needed. - ` - This is an alias for ``digv x``. + Dig a vein across z-levels, digging stairs as needed. This is an alias for + ``digv x``. ``digl [x] [undo] [-p]`` - :index:`Dig all of the selected layer stone. - ` If ``undo`` is specified, - removes the designation instead (for if you accidentally set 50 levels at - once). + Dig all of the selected layer stone. If ``undo`` is specified, removes the + designation instead (for if you accidentally set 50 levels at once). ``diglx [-p]`` - :index:`Dig layer stone across z-levels, digging stairs as needed. - ` This - is an alias for ``digl x``. + Dig layer stone across z-levels, digging stairs as needed. This is an alias + for ``digl x``. ``digcircle [] [] [] [] [-p]`` - :index:`Designate circles. ` The diameter - is the number of tiles across the center of the circle that you want to dig. - See the `digcircle`_ section below for options. + Designate circles. The diameter is the number of tiles across the center of + the circle that you want to dig. See the `digcircle`_ section below for + options. ``digtype [] [-p]`` - :index:`Designate all vein tiles of the selected type. - ` See the `digtype`_ - section below for options. + Designate all vein tiles of the selected type. See the `digtype`_ section + below for options. ``digexp [] [] [-p]`` - :index:`Designate dig patterns for exploratory mining. - ` See the `digexp`_ - section below for options + Designate dig patterns for exploratory mining. See the `digexp`_ section + below for options. All commands support specifying the priority of the dig designations with ``-p``, where the number is from 1 to 7. If a priority is not specified, diff --git a/docs/plugins/digFlood.rst b/docs/plugins/digFlood.rst index 1a17c32a7..60bbc9423 100644 --- a/docs/plugins/digFlood.rst +++ b/docs/plugins/digFlood.rst @@ -1,13 +1,16 @@ digFlood ======== -**Tags:** `tag/fort`, `tag/auto`, `tag/map` -:dfhack-keybind:`digFlood` - -:index:`Digs out veins as they are discovered. -` It will only dig out -appropriate tiles that are adjacent to a just-finished dig job, so if you want -to autodig a vein that has already been discovered, you may need to manually -designate one tile of the tile for digging to get started. + +.. dfhack-tool:: + :summary: Digs out veins as they are discovered. + :tags: fort auto map + +Once you register specific vein types, this tool will automatically designate +tiles of those types of veins for digging as your miners complete adjacent +mining jobs. Note that it will *only* dig out tiles that are adjacent to a +just-finished dig job, so if you want to autodig a vein that has already been +discovered, you may need to manually designate one tile of the tile for digging +to get started. Usage: diff --git a/docs/plugins/diggingInvaders.rst b/docs/plugins/diggingInvaders.rst index 4891bf8d4..df54e7008 100644 --- a/docs/plugins/diggingInvaders.rst +++ b/docs/plugins/diggingInvaders.rst @@ -1,10 +1,9 @@ diggingInvaders =============== -**Tags:** `tag/fort`, `tag/mod`, `tag/map` -:dfhack-keybind:`diggingInvaders` -:index:`Invaders dig and destroy to get to your dwarves. -` +.. dfhack-tool:: + :summary: Invaders dig and destroy to get to your dwarves. + :tags: fort mod map Usage: diff --git a/docs/plugins/dwarfmonitor.rst b/docs/plugins/dwarfmonitor.rst index a7f42bb81..73d8a8c19 100644 --- a/docs/plugins/dwarfmonitor.rst +++ b/docs/plugins/dwarfmonitor.rst @@ -1,11 +1,11 @@ dwarfmonitor ============ -**Tags:** `tag/fort`, `tag/inspection`, `tag/units` -:dfhack-keybind:`dwarfmonitor` -:index:`Measure fort happiness and efficiency. -` Also show heads-up -display widgets with live fort statistics. +.. dfhack-tool:: + :summary: Measure fort happiness and efficiency. + :tags: fort inspection units + +It can also show heads-up display widgets with live fort statistics. Usage: diff --git a/docs/plugins/dwarfvet.rst b/docs/plugins/dwarfvet.rst index 2db4a9595..f607e85cd 100644 --- a/docs/plugins/dwarfvet.rst +++ b/docs/plugins/dwarfvet.rst @@ -1,10 +1,9 @@ dwarfvet ======== -**Tags:** `tag/fort`, `tag/mod`, `tag/animals` -:dfhack-keybind:`dwarfvet` -:index:`Allows animals to be treated at animal hospitals. -` +.. dfhack-tool:: + :summary: Allows animals to be treated at animal hospitals. + :tags: fort mod animals Annoyed your dragons become useless after a minor injury? Well, with dwarfvet, injured animals will be treated at an animal hospital, which is simply a hospital diff --git a/docs/plugins/embark-assistant.rst b/docs/plugins/embark-assistant.rst index b9a7e4ee2..22c18996a 100644 --- a/docs/plugins/embark-assistant.rst +++ b/docs/plugins/embark-assistant.rst @@ -1,14 +1,15 @@ embark-assistant ================ -**Tags:** `tag/fort`, `tag/embark`, `tag/interface` -:dfhack-keybind:`embark-assistant` -:index:`Embark site selection support. -` Run this command while the -pre-embark screen is displayed to show extended (and correct(?)) resource -information for the embark rectangle as well as normally undisplayed sites in -the current embark region. You will also have access to a site selection tool -with far more options than DF's vanilla search tool. +.. dfhack-tool:: + :summary: Embark site selection support. + :tags: fort embark interface + +Run this command while the pre-embark screen is displayed to show extended (and +reasonably correct) resource information for the embark rectangle as well as +normally undisplayed sites in the current embark region. You will also have +access to a site selection tool with far more options than DF's vanilla search +tool. If you enable the plugin, you'll also be able to invoke ``embark-assistant`` with the :kbd:`A` key on the pre-embark screen. diff --git a/docs/plugins/embark-tools.rst b/docs/plugins/embark-tools.rst index 52532e4f2..58b02d47e 100644 --- a/docs/plugins/embark-tools.rst +++ b/docs/plugins/embark-tools.rst @@ -1,10 +1,9 @@ embark-tools ============ -**Tags:** `tag/fort`, `tag/embark`, `tag/interface` -:dfhack-keybind:`embark-tools` -:index:`Extend the embark screen functionality. -` +.. dfhack-tool:: + :summary: Extend the embark screen functionality. + :tags: fort embark interface Usage:: diff --git a/docs/plugins/eventful.rst b/docs/plugins/eventful.rst index 102287b77..d5bd55956 100644 --- a/docs/plugins/eventful.rst +++ b/docs/plugins/eventful.rst @@ -1,7 +1,9 @@ eventful ======== -**Tags:** `tag/dev`, `tag/mod` -Provides a Lua API for reacting to in-game events. +.. dfhack-tool:: + :summary: Provides a Lua API for reacting to in-game events. + :tags: dev mod + :no-command: See `eventful-api` for details. diff --git a/docs/plugins/fastdwarf.rst b/docs/plugins/fastdwarf.rst index 2e09b8a4d..7042a71a3 100644 --- a/docs/plugins/fastdwarf.rst +++ b/docs/plugins/fastdwarf.rst @@ -1,9 +1,9 @@ fastdwarf ========= -**Tags:** `tag/fort`, `tag/armok`, `tag/units` -:dfhack-keybind:`fastdwarf` -Dwarves teleport and/or finish jobs instantly. +.. dfhack-tool:: + :summary: Dwarves teleport and/or finish jobs instantly. + :tags: fort armok units Usage:: diff --git a/docs/plugins/filltraffic.rst b/docs/plugins/filltraffic.rst index acc4dabc8..ea48fd385 100644 --- a/docs/plugins/filltraffic.rst +++ b/docs/plugins/filltraffic.rst @@ -3,24 +3,28 @@ filltraffic =========== -**Tags:** `tag/fort`, `tag/productivity`, `tag/design`, `tag/map` -:dfhack-keybind:`filltraffic` -:dfhack-keybind:`alltraffic` -:dfhack-keybind:`restrictice` -:dfhack-keybind:`restrictliquids` - -Usage: - -``filltraffic []`` - Set traffic designations using flood-fill starting at the cursor. Flood - filling stops at walls and doors. -``alltraffic `` - Set traffic designations for every single tile of the map - useful for - resetting traffic designations. -``restrictice`` - Restrict traffic on all tiles on top of visible ice. -``restrictliquids`` - Restrict traffic on all visible tiles with liquid. + +.. dfhack-tool:: + :summary: Set traffic designations using flood-fill starting at the cursor. + :tags: fort productivity design map + +.. dfhack-command:: alltraffic + :summary: Set traffic designations for every single tile of the map. + +.. dfhack-command:: restrictice + :summary: Restrict traffic on all tiles on top of visible ice. + +.. dfhack-command:: restrictliquids + :summary: Restrict traffic on all visible tiles with liquid. + +Usage:: + + filltraffic [] + alltraffic + restrictice + restrictliquids + +For ``filltraffic``, flood filling stops at walls and doors. Examples -------- diff --git a/docs/plugins/fix-unit-occupancy.rst b/docs/plugins/fix-unit-occupancy.rst index 28479791f..117f97467 100644 --- a/docs/plugins/fix-unit-occupancy.rst +++ b/docs/plugins/fix-unit-occupancy.rst @@ -1,10 +1,12 @@ fix-unit-occupancy ================== -**Tags:** `tag/fort`, `tag/fix`, `tag/map` -:dfhack-keybind:`` -Fix phantom unit occupancy issues. For example, if you see "unit blocking tile" -messages that you can't account for (:bug:`3499`), this tool can help. +.. dfhack-tool:: + :summary: Fix phantom unit occupancy issues. + :tags: fort fix map + +If you see "unit blocking tile" messages that you can't account for +(:bug:`3499`), this tool can help. Usage:: diff --git a/docs/plugins/fixveins.rst b/docs/plugins/fixveins.rst index 873e1770a..045b3c8da 100644 --- a/docs/plugins/fixveins.rst +++ b/docs/plugins/fixveins.rst @@ -1,10 +1,12 @@ fixveins ======== -**Tags:** `tag/fort`, `tag/fix`, `tag/map` -:dfhack-keybind:`fixveins` -Restore missing mineral inclusions. This tool can also remove invalid references -to mineral inclusions if you broke your embark with tools like `tiletypes`. +.. dfhack-tool:: + :summary: Restore missing mineral inclusions. + :tags: fort fix map + +This tool can also remove invalid references to mineral inclusions if you broke +your embark with tools like `tiletypes`. Usage:: diff --git a/docs/plugins/flows.rst b/docs/plugins/flows.rst index a347f00e0..994057878 100644 --- a/docs/plugins/flows.rst +++ b/docs/plugins/flows.rst @@ -1,10 +1,12 @@ flows ===== -**Tags:** `tag/fort`, `tag/inspection`, `tag/map` -:dfhack-keybind:`flows` -Counts map blocks with flowing liquids.. If you suspect that your magma sea -leaks into HFS, you can use this tool to be sure without revealing the map. +.. dfhack-tool:: + :summary: Counts map blocks with flowing liquids. + :tags: fort inspection map + +If you suspect that your magma sea leaks into HFS, you can use this tool to be +sure without revealing the map. Usage:: diff --git a/docs/plugins/follow.rst b/docs/plugins/follow.rst index 5f43e2fdd..b6bc610b2 100644 --- a/docs/plugins/follow.rst +++ b/docs/plugins/follow.rst @@ -1,11 +1,13 @@ follow ====== -**Tags:** `tag/fort`, `tag/interface`, `tag/units` -:dfhack-keybind:`follow` -Make the screen follow the selected unit. Once you exit from the current menu or -cursor mode, the screen will stay centered on the unit. Handy for watching -dwarves running around. Deactivated by moving the cursor manually. +.. dfhack-tool:: + :summary: Make the screen follow the selected unit. + :tags: fort interface units + +Once you exit from the current menu or cursor mode, the screen will stay +centered on the unit. Handy for watching dwarves running around. Deactivated by +moving the cursor manually. Usage:: diff --git a/docs/plugins/forceequip.rst b/docs/plugins/forceequip.rst index 51d48390c..acfd8f462 100644 --- a/docs/plugins/forceequip.rst +++ b/docs/plugins/forceequip.rst @@ -1,14 +1,15 @@ forceequip ========== -**Tags:** `tag/adventure`, `tag/fort`, `tag/items`, `tag/units` -:dfhack-keybind:`forceequip` -Move items into a unit's inventory. This tool is typically used to equip -specific clothing/armor items onto a dwarf, but can also be used to put armor -onto a war animal or to add unusual items (such as crowns) to any unit. Make -sure the unit you want to equip is standing on the target items, which must be -on the ground and be unforbidden. If multiple units are standing on the same -tile, the first one will be equipped. +.. dfhack-tool:: + :summary: Move items into a unit's inventory. + :tags: adventure fort items units + +This tool is typically used to equip specific clothing/armor items onto a dwarf, +but can also be used to put armor onto a war animal or to add unusual items +(such as crowns) to any unit. Make sure the unit you want to equip is standing +on the target items, which must be on the ground and be unforbidden. If multiple +units are standing on the same tile, the first one will be equipped. The most reliable way to set up the environment for this command is to pile target items on a tile of floor with a garbage dump activity zone or the diff --git a/docs/plugins/generated-creature-renamer.rst b/docs/plugins/generated-creature-renamer.rst index 39983940b..6af13595a 100644 --- a/docs/plugins/generated-creature-renamer.rst +++ b/docs/plugins/generated-creature-renamer.rst @@ -1,12 +1,20 @@ generated-creature-renamer ========================== -**Tags:** `tag/adventure`, `tag/fort`, `tag/legends`, `tag/units` -:dfhack-keybind:`list-generated` -:dfhack-keybind:`save-generated-raws` -Automatically renames generated creatures. Now, forgotten beasts, titans, -necromancer experiments, etc. will have raw token names that match the -description given in-game instead of unreadable generated strings. +.. dfhack-tool:: + :summary: Automatically renames generated creatures. + :tags: adventure fort legends units + :no-command: + +.. dfhack-command:: list-generated + :summary: List the token names of all generated creatures. + +.. dfhack-command:: save-generated-raws + :summary: Export a creature graphics file for modding. + +Now, forgotten beasts, titans, necromancer experiments, etc. will have raw token +names that match the description given in-game instead of unreadable generated +strings. Usage: diff --git a/docs/plugins/getplants.rst b/docs/plugins/getplants.rst index 21325e8f2..502f6e9ae 100644 --- a/docs/plugins/getplants.rst +++ b/docs/plugins/getplants.rst @@ -1,10 +1,12 @@ getplants ========= -**Tags:** `tag/fort`, `tag/productivity` -:dfhack-keybind:`getplants` -Designate trees for chopping and shrubs for gathering. Specify the types of -trees to cut down and/or shrubs to gather by their plant names. +.. dfhack-tool:: + :summary: Designate trees for chopping and shrubs for gathering. + :tags: fort productivity + +Specify the types of trees to cut down and/or shrubs to gather by their plant +names. Usage: diff --git a/docs/plugins/hotkeys.rst b/docs/plugins/hotkeys.rst index fbf4a9a76..7d30d486e 100644 --- a/docs/plugins/hotkeys.rst +++ b/docs/plugins/hotkeys.rst @@ -1,11 +1,12 @@ hotkeys ======= -**Tags:** `tag/system`, `tag/productivity`, `tag/interface` -:dfhack-keybind:`hotkeys` -Show all dfhack keybindings in current context. The command opens an in-game -screen showing which DFHack keybindings are active in the current context. -See also `hotkey-notes`. +.. dfhack-tool:: + :summary: Show all dfhack keybindings for the current context. + :tags: system productivity interface + +The command opens an in-game screen showing which DFHack keybindings are active +in the current context. See also `hotkey-notes`. Usage:: diff --git a/docs/plugins/infiniteSky.rst b/docs/plugins/infiniteSky.rst index ceb08aa0e..46f30c24c 100644 --- a/docs/plugins/infiniteSky.rst +++ b/docs/plugins/infiniteSky.rst @@ -1,10 +1,13 @@ infiniteSky =========== -**Tags:** `tag/fort`, `tag/map` -:dfhack-keybind:`infiniteSky` -Automatically allocates new z-levels of sky at the top of the map as you build -up, or on request allocates many levels all at once. +.. dfhack-tool:: + :summary: Automatically allocates new z-levels of sky + :tags: fort map + +If enabled, this plugin will automatically allocate new z-levels of sky at the +top of the map as you build up. Or it can allocate one or many additional levels +at your command. Usage: diff --git a/docs/plugins/isoworldremote.rst b/docs/plugins/isoworldremote.rst index 84babe66a..1fa439b29 100644 --- a/docs/plugins/isoworldremote.rst +++ b/docs/plugins/isoworldremote.rst @@ -1,5 +1,9 @@ isoworldremote ============== -**Tags:** `tag/dev`, `tag/mod` -Provides a `remote API ` used by Isoworld. +.. dfhack-tool:: + :summary: Provides a remote API used by Isoworld. + :tags: dev mod + :no-command: + +See `remote` for related remote APIs. diff --git a/docs/plugins/jobutils.rst b/docs/plugins/jobutils.rst index 5dcb0c85f..46b221f89 100644 --- a/docs/plugins/jobutils.rst +++ b/docs/plugins/jobutils.rst @@ -2,12 +2,20 @@ jobutils ======== -**Tags:** `tag/fort`, `tag/inspection`, `tag/jobs` -:dfhack-keybind:`job` -:dfhack-keybind:`job-duplicate` -:dfhack-keybind:`job-material` -Inspect or modify details of workshop jobs. +.. dfhack-tool:: + :summary: Provides commands for interacting with jobs. + :tags: fort inspection jobs + :no-command: + +.. dfhack-command:: job + :summary: Inspect or modify details of workshop jobs. + +.. dfhack-command:: job-duplicate + :summary: Duplicates the highlighted job. + +.. dfhack-command:: job-material + :summary: Alters the material of the selected job. Usage: diff --git a/docs/plugins/labormanager.rst b/docs/plugins/labormanager.rst index 1a25cedae..b168a3b7a 100644 --- a/docs/plugins/labormanager.rst +++ b/docs/plugins/labormanager.rst @@ -1,12 +1,14 @@ labormanager ============ -**Tags:** `tag/fort`, `tag/auto`, `tag/labors` -:dfhack-keybind:`labormanager` -Automatically manage dwarf labors. Labormanager is derived from `autolabor` -but uses a completely different approach to assigning jobs to dwarves. While -autolabor tries to keep as many dwarves busy as possible, labormanager instead -strives to get jobs done as quickly as possible. +.. dfhack-tool:: + :summary: Automatically manage dwarf labors. + :tags: fort auto labors + +Labormanager is derived from `autolabor` but uses a completely different +approach to assigning jobs to dwarves. While autolabor tries to keep as many +dwarves busy as possible, labormanager instead strives to get jobs done as +quickly as possible. Labormanager frequently scans the current job list, current list of dwarves, and the map to determine how many dwarves need to be assigned to what labors in diff --git a/docs/plugins/lair.rst b/docs/plugins/lair.rst index 43bb06072..f42cc0777 100644 --- a/docs/plugins/lair.rst +++ b/docs/plugins/lair.rst @@ -1,10 +1,11 @@ lair ==== -**Tags:** `tag/fort`, `tag/armok`, `tag/map` -:dfhack-keybind:`lair` -Mark the map as a monster lair. This avoids item scatter when the fortress is -abandoned. +.. dfhack-tool:: + :summary: Mark the map as a monster lair. + :tags: fort armok map + +This avoids item scatter when the fortress is abandoned. Usage: diff --git a/docs/plugins/liquids.rst b/docs/plugins/liquids.rst index 808089591..a498364fc 100644 --- a/docs/plugins/liquids.rst +++ b/docs/plugins/liquids.rst @@ -2,9 +2,13 @@ liquids ======= -**Tags:** `tag/adventure`, `tag/fort`, `tag/armok`, `tag/map` -:dfhack-keybind:`liquids` -:dfhack-keybind:`liquids-here` + +.. dfhack-tool:: + :summary: Place magma, water or obsidian. + :tags: adventure fort armok map + +.. dfhack-command:: liquids-here + :summary: Spawn liquids on the selected tile. Place magma, water or obsidian. See `gui/liquids` for an in-game interface for this functionality. diff --git a/docs/plugins/luasocket.rst b/docs/plugins/luasocket.rst index cbbf09f7e..24b30c7a6 100644 --- a/docs/plugins/luasocket.rst +++ b/docs/plugins/luasocket.rst @@ -1,7 +1,9 @@ luasocket ========= -**Tags:** `tag/dev`, `tag/mod` -Provides a Lua API for accessing network sockets. +.. dfhack-tool:: + :summary: Provides a Lua API for accessing network sockets. + :tags: dev mod + :no-command: See `luasocket-api` for details. diff --git a/docs/plugins/manipulator.rst b/docs/plugins/manipulator.rst index 07d1d4ab6..26223587d 100644 --- a/docs/plugins/manipulator.rst +++ b/docs/plugins/manipulator.rst @@ -1,9 +1,12 @@ manipulator =========== -**Tags:** `tag/fort`, `tag/productivity`, `tag/interface`, `tag/labors` -An in-game labor management interface. It is equivalent to the popular Dwarf -Therapist utility. +.. dfhack-tool:: + :summary: An in-game labor management interface. + :tags: fort productivity interface labors + :no-command: + +It is equivalent to the popular Dwarf Therapist utility. To activate, open the unit screen and press :kbd:`l`. diff --git a/docs/plugins/map-render.rst b/docs/plugins/map-render.rst index 6b7f1a5d9..7754af8b7 100644 --- a/docs/plugins/map-render.rst +++ b/docs/plugins/map-render.rst @@ -1,7 +1,9 @@ map-render ========== -**Tags:** `tag/dev` -Provides a Lua API for rerendering portions of the map. +.. dfhack-tool:: + :summary: Provides a Lua API for rerendering portions of the map. + :tags: dev + :no-command: See `map-render-api` for details. diff --git a/docs/plugins/misery.rst b/docs/plugins/misery.rst index 5d11f98cb..af71ae19a 100644 --- a/docs/plugins/misery.rst +++ b/docs/plugins/misery.rst @@ -1,9 +1,9 @@ misery ====== -**Tags:** `tag/fort`, `tag/armok`, `tag/units` -:dfhack-keybind:`misery` -Increase the intensity of negative dwarven thoughts. +.. dfhack-tool:: + :summary: Increase the intensity of negative dwarven thoughts. + :tags: fort armok units When enabled, negative thoughts that your dwarves have will multiply by the specified factor. diff --git a/docs/plugins/mode.rst b/docs/plugins/mode.rst index 8c33d6ec3..db94e6bac 100644 --- a/docs/plugins/mode.rst +++ b/docs/plugins/mode.rst @@ -1,9 +1,9 @@ mode ==== -**Tags:** `tag/dev` -:dfhack-keybind:`mode` -This command lets you see and change the game mode directly. +.. dfhack-tool:: + :summary: See and change the game mode. + :tags: dev .. warning:: diff --git a/docs/plugins/mousequery.rst b/docs/plugins/mousequery.rst index 7e01de6d0..eb6550d60 100644 --- a/docs/plugins/mousequery.rst +++ b/docs/plugins/mousequery.rst @@ -1,7 +1,9 @@ mousequery ========== -**Tags:** `tag/fort`, `tag/productivity`, `tag/interface` -:dfhack-keybind:`mousequery` + +.. dfhack-tool:: + :summary: Adds mouse controls to the DF interface. + :tags: fort productivity interface Adds mouse controls to the DF interface. For example, with ``mousequery`` you can click on buildings to configure them, hold the mouse button to draw dig diff --git a/docs/plugins/nestboxes.rst b/docs/plugins/nestboxes.rst index 1558a7357..9182eee09 100644 --- a/docs/plugins/nestboxes.rst +++ b/docs/plugins/nestboxes.rst @@ -1,11 +1,14 @@ nestboxes ========= -**Tags:** `tag/fort`, `tag/auto`, `tag/animals` -Protect fertile eggs incubating in a nestbox. This plugin will automatically -scan for and forbid fertile eggs incubating in a nestbox so that dwarves won't -come to collect them for eating. The eggs will hatch normally, even when -forbidden. +.. dfhack-tool:: + :summary: Protect fertile eggs incubating in a nestbox. + :tags: fort auto animals + :no-command: + +This plugin will automatically scan for and forbid fertile eggs incubating in a +nestbox so that dwarves won't come to collect them for eating. The eggs will +hatch normally, even when forbidden. Usage:: diff --git a/docs/plugins/orders.rst b/docs/plugins/orders.rst index 3be1f82b2..9403c6c8e 100644 --- a/docs/plugins/orders.rst +++ b/docs/plugins/orders.rst @@ -1,9 +1,9 @@ orders ====== -**Tags:** `tag/fort`, `tag/productivity`, `tag/jobs` -:dfhack-keybind:`orders` -Manage manager orders. +.. dfhack-tool:: + :summary: Manage manager orders. + :tags: fort productivity jobs Usage: diff --git a/docs/plugins/pathable.rst b/docs/plugins/pathable.rst index 6368d1c7e..800580017 100644 --- a/docs/plugins/pathable.rst +++ b/docs/plugins/pathable.rst @@ -1,8 +1,10 @@ pathable ======== -**Tags:** `tag/dev`, `tag/inspection`, `tag/interface`, `tag/map` -Marks tiles that are reachable from the cursor. This plugin provides a Lua API, -but no direct commands. +.. dfhack-tool:: + :summary: Marks tiles that are reachable from the cursor. + :tags: dev inspection interface map + :no-command: -See `pathable-api` for details. +This plugin provides a Lua API, but no direct commands. See `pathable-api` for +details. diff --git a/docs/plugins/petcapRemover.rst b/docs/plugins/petcapRemover.rst index 95a9e60bd..f3d011308 100644 --- a/docs/plugins/petcapRemover.rst +++ b/docs/plugins/petcapRemover.rst @@ -1,16 +1,17 @@ petcapRemover ============= -**Tags:** `tag/fort`, `tag/armok`, `tag/animals` -:dfhack-keybind:`petcapRemover` -Modify the pet population cap. In vanilla DF, pets will not reproduce unless the -population is below 50 and the number of children of that species is below a -certain percentage. This plugin allows removing these restrictions and setting -your own thresholds. Pets still require PET or PET_EXOTIC tags in order to -reproduce. In order to make population more stable and avoid sudden population -booms as you go below the raised population cap, this plugin counts pregnancies -toward the new population cap. It can still go over, but only in the case of -multiple births. +.. dfhack-tool:: + :summary: Modify the pet population cap. + :tags: fort armok animals + +In vanilla DF, pets will not reproduce unless the population is below 50 and the +number of children of that species is below a certain percentage. This plugin +allows removing these restrictions and setting your own thresholds. Pets still +require PET or PET_EXOTIC tags in order to reproduce. In order to make +population more stable and avoid sudden population booms as you go below the +raised population cap, this plugin counts pregnancies toward the new population +cap. It can still go over, but only in the case of multiple births. Usage: diff --git a/docs/plugins/plants.rst b/docs/plugins/plants.rst index 2021bc103..d28119af9 100644 --- a/docs/plugins/plants.rst +++ b/docs/plugins/plants.rst @@ -2,10 +2,14 @@ plants ====== -**Tags:** `tag/adventure`, `tag/fort`, `tag/armok`, `tag/map` -:dfhack-keybind:`plant` -Grow shrubs or trees. +.. dfhack-tool:: + :summary: Provides commands that interact with plants. + :tags: adventure fort armok map + :no-command: + +.. dfhack-command:: plant + :summary: Create a plant or make an existing plant grow up. Usage: diff --git a/docs/plugins/power-meter.rst b/docs/plugins/power-meter.rst index 72a49b72c..01e75491a 100644 --- a/docs/plugins/power-meter.rst +++ b/docs/plugins/power-meter.rst @@ -1,7 +1,11 @@ power-meter =========== -**Tags:** `tag/fort`, `tag/mod`, `tag/buildings` -Allow presure plates to measure power. If you run `gui/power-meter` while -building a pressure plate, the pressure plate can be modified to detect power -being supplied to gear boxes built in the four adjacent N/S/W/E tiles. +.. dfhack-tool:: + :summary: Allow presure plates to measure power. + :tags: fort mod buildings + :no-command: + +If you run `gui/power-meter` while building a pressure plate, the pressure +plate can be modified to detect power being supplied to gear boxes built in the +four adjacent N/S/W/E tiles. diff --git a/docs/plugins/probe.rst b/docs/plugins/probe.rst index 0285bb821..54436be68 100644 --- a/docs/plugins/probe.rst +++ b/docs/plugins/probe.rst @@ -1,11 +1,15 @@ probe ===== -**Tags:** `tag/adventure`, `tag/fort`, `tag/inspection`, `tag/map` -:dfhack-keybind:`probe` -:dfhack-keybind:`bprobe` -:dfhack-keybind:`cprobe` -Display low-level properties of selected objects. +.. dfhack-tool:: + :summary: Display low-level properties of the selected tile. + :tags: adventure fort inspection map + +.. dfhack-command:: bprobe + :summary: Display low-level properties of the selected building. + +.. dfhack-command:: cprobe + :summary: Display low-level properties of the selected unit. Usage: diff --git a/docs/plugins/prospector.rst b/docs/plugins/prospector.rst index 7ff3b4313..dc6204c06 100644 --- a/docs/plugins/prospector.rst +++ b/docs/plugins/prospector.rst @@ -2,11 +2,17 @@ prospector ========== -**Tags:** `tag/fort`, `tag/embark`, `tag/inspection`, `tag/map` -:dfhack-keybind:`prospect` -Shows a summary of resources that exist on the map. It can also calculate an -estimate of resources available in the selected embark area. +.. dfhack-tool:: + :summary: Provides commands that help you analyze natural resources. + :tags: fort embark inspection map + :no-command: + +.. dfhack-command:: prospect + :summary: Shows a summary of resources that exist on the map. + +It can also calculate an estimate of resources available in the selected embark +area. Usage:: diff --git a/docs/plugins/regrass.rst b/docs/plugins/regrass.rst index 98590a73e..72f077fcd 100644 --- a/docs/plugins/regrass.rst +++ b/docs/plugins/regrass.rst @@ -1,14 +1,15 @@ regrass ======= -**Tags:** `tag/adventure`, `tag/fort`, `tag/armok`, `tag/animals` -:dfhack-keybind:`regrass` -Regrows all the grass. Use this command if your grazers have eaten everything -down to the dirt. +.. dfhack-tool:: + :summary: Regrows all the grass. + :tags: adventure fort armok animals + +Use this command if your grazers have eaten everything down to the dirt. Usage:: regrass [max] -Specify the 'max' option to pack more grass onto a tile than what the game +Specify the 'max' keyword to pack more grass onto a tile than what the game normally allows to give your grazers extra chewing time. diff --git a/docs/plugins/rename.rst b/docs/plugins/rename.rst index 34695e19a..02bc04c2c 100644 --- a/docs/plugins/rename.rst +++ b/docs/plugins/rename.rst @@ -1,9 +1,11 @@ rename ====== -**Tags:** `tag/adventure`, `tag/fort`, `tag/productivity` -:dfhack-keybind:`rename` -Easily rename things. Use `gui/rename` for an in-game interface. +.. dfhack-tool:: + :summary: Easily rename things. + :tags: adventure fort productivity + +Use `gui/rename` for an in-game interface. Usage: diff --git a/docs/plugins/rendermax.rst b/docs/plugins/rendermax.rst index 83e9ee461..680676fa3 100644 --- a/docs/plugins/rendermax.rst +++ b/docs/plugins/rendermax.rst @@ -1,10 +1,12 @@ rendermax ========= -**Tags:** `tag/adventure`, `tag/fort`, `tag/mod` -:dfhack-keybind:`rendermax` -Modify the map lighting. This plugin provides a collection of OpenGL lighting -filters that affect how the map is drawn to the screen. +.. dfhack-tool:: + :summary: Modify the map lighting. + :tags: adventure fort mod + +This plugin provides a collection of OpenGL lighting filters that affect how the +map is drawn to the screen. Usage: diff --git a/docs/plugins/resume.rst b/docs/plugins/resume.rst index 2f28d7083..0713026e4 100644 --- a/docs/plugins/resume.rst +++ b/docs/plugins/resume.rst @@ -1,13 +1,18 @@ resume ====== -**Tags:** `tag/fort`, `tag/productivity` -:dfhack-keybind:`resume` - -Color planned buildings based on their suspend status. When enabled, this plugin -will display a colored 'X' over suspended buildings. When run as a command, it -can resume all suspended building jobs, allowing you to quickly recover if a -bunch of jobs were suspended due to the workers getting scared off by wildlife -or items temporarily blocking buildling sites. + +.. dfhack-tool:: + :summary: Color planned buildings based on their suspend status. + :tags: fort productivity + :no-command: + +.. dfhack-command:: resume + :summary: Resume all suspended building jobs. + +When enabled, this plugin will display a colored 'X' over suspended buildings. +When run as a command, it can resume all suspended building jobs, allowing you +to quickly recover if a bunch of jobs were suspended due to the workers getting +scared off by wildlife or items temporarily blocking buildling sites. Usage:: diff --git a/docs/plugins/reveal.rst b/docs/plugins/reveal.rst index fb69d9a02..122280a1e 100644 --- a/docs/plugins/reveal.rst +++ b/docs/plugins/reveal.rst @@ -2,17 +2,29 @@ reveal ====== -**Tags:** `tag/adventure`, `tag/fort`, `tag/inspection`, `tag/armok`, `tag/map` -:dfhack-keybind:`reveal` -:dfhack-keybind:`unreveal` -:dfhack-keybind:`revforget` -:dfhack-keybind:`revtoggle` -:dfhack-keybind:`revflood` -:dfhack-keybind:`nopause` - -Reveals the map. This reveals all z-layers in fort mode. It also works in -adventure mode, but any of its effects are negated once you move. When you use -it this way, you don't need to run ``unreveal`` to hide the map again. + +.. dfhack-tool:: + :summary: Reveals the map. + :tags: adventure fort inspection armok map + +.. dfhack-tool:: unreveal + :summary: Hides previously hidden tiles again. + +.. dfhack-tool:: revforget + :summary: Discard records about what was visible before revealing the map. + +.. dfhack-tool:: revtoggle + :summary: Switch between reveal and unreveal. + +.. dfhack-tool:: revflood + :summary: Hide everything, then reveal tiles with a path to the cursor. + +.. dfhack-tool:: nopause + :summary: Disable pausing. + +This reveals all z-layers in fort mode. It also works in adventure mode, but any +of its effects are negated once you move. When you use it this way, you don't +need to run ``unreveal`` to hide the map again. Usage: diff --git a/docs/plugins/ruby.rst b/docs/plugins/ruby.rst index d3b89d3a9..f808735d4 100644 --- a/docs/plugins/ruby.rst +++ b/docs/plugins/ruby.rst @@ -2,12 +2,17 @@ ruby ==== -**Tags:** `tag/dev` -:dfhack-keybind:`rb` -:dfhack-keybind:`rb_eval` -Allow Ruby scripts to be executed. When invoked as a command, you can Eval() a -ruby string. +.. dfhack-tool:: + :summary: Allow Ruby scripts to be executed as DFHack commands. + :tags: dev + :no-command: + +.. dfhack-command:: rb + :summary: Eval() a ruby string. + +.. dfhack-command:: rb_eval + :summary: Eval() a ruby string. Usage:: diff --git a/docs/plugins/search.rst b/docs/plugins/search.rst index 41ae1c922..937e09885 100644 --- a/docs/plugins/search.rst +++ b/docs/plugins/search.rst @@ -2,12 +2,16 @@ search ====== -**Tags:** `tag/fort`, `tag/productivity`, `tag/interface` -Adds search capabilities to the UI. The Stocks, Animals, Trading, Stockpile, -Noble (assignment candidates), Military (position candidates), Burrows (unit -list), Rooms, Announcements, Job List, and Unit List screens all get hotkeys -that allow you to dynamically filter the displayed lists. +.. dfhack-tool:: + :summary: Adds search capabilities to the UI. + :tags: fort productivity interface + :no-command: + +Search options are added to the Stocks, Animals, Trading, Stockpile, Noble +aassignment candidates), Military (position candidates), Burrows (unit list), +Rooms, Announcements, Job List, and Unit List screens all get hotkeys that allow +you to dynamically filter the displayed lists. Usage:: diff --git a/docs/plugins/seedwatch.rst b/docs/plugins/seedwatch.rst index bd51fdd2e..1aaa04ee3 100644 --- a/docs/plugins/seedwatch.rst +++ b/docs/plugins/seedwatch.rst @@ -1,9 +1,9 @@ seedwatch ========= -**Tags:** `tag/fort`, `tag/auto` -:dfhack-keybind:`seedwatch` -Manages seed and plant cooking based on seed stock levels. +.. dfhack-tool:: + :summary: Manages seed and plant cooking based on seed stock levels. + :tags: fort auto Each seed type can be assigned a target. If the number of seeds of that type falls below that target, then the plants and seeds of that type will be excluded diff --git a/docs/plugins/showmood.rst b/docs/plugins/showmood.rst index 42af0e7a8..da67b5803 100644 --- a/docs/plugins/showmood.rst +++ b/docs/plugins/showmood.rst @@ -1,9 +1,9 @@ showmood ======== -**Tags:** `tag/fort`, `tag/inspection`, `tag/jobs` -:dfhack-keybind:`showmood` -Shows all items needed for the active strange mood. +.. dfhack-tool:: + :summary: Shows all items needed for the active strange mood. + :tags: fort inspection jobs Usage:: diff --git a/docs/plugins/siege-engine.rst b/docs/plugins/siege-engine.rst index 9255110bd..06ff963b7 100644 --- a/docs/plugins/siege-engine.rst +++ b/docs/plugins/siege-engine.rst @@ -1,10 +1,13 @@ siege-engine ============ -**Tags:** `tag/fort`, `tag/mod`, `tag/buildings` -Extend the functionality and usability of siege engines. Siege engines in DF -haven't been updated since the game was 2D, and can only aim in four -directions. To make them useful above-ground, this plugin allows you to: +.. dfhack-tool:: + :summary: Extend the functionality and usability of siege engines. + :tags: fort mod buildings + :no-command: + +Siege engines in DF haven't been updated since the game was 2D, and can only aim +in four directions. To make them useful above-ground, this plugin allows you to: * link siege engines to stockpiles * restrict operator skill levels (like workshops) diff --git a/docs/plugins/sort.rst b/docs/plugins/sort.rst index f3ba6e6fb..c746f1c79 100644 --- a/docs/plugins/sort.rst +++ b/docs/plugins/sort.rst @@ -1,10 +1,16 @@ sort ==== -**Tags:** `tag/fort`, `tag/productivity`, `tag/interface` -:dfhack-keybind:`sort-items` -:dfhack-keybind:`sort-units` -Sort the visible item or unit list. +.. dfhack-tool:: + :summary: Sort lists shown in the DF interface. + :tags: fort productivity interface + :no-command: + +.. dfhack-command:: sort-items + :summary: Sort the visible item list. + +.. dfhack-command:: sort-units + :summary: Sort the visible unit list. Usage:: diff --git a/docs/plugins/spectate.rst b/docs/plugins/spectate.rst index 08cc3f819..7f448ebfb 100644 --- a/docs/plugins/spectate.rst +++ b/docs/plugins/spectate.rst @@ -1,8 +1,10 @@ spectate ======== -**Tags:** `tag/fort`, `tag/units` -Automatically follow exciting dwarves. +.. dfhack-tool:: + :summary: Automatically follow exciting dwarves. + :tags: fort units + :no-command: Usage:: diff --git a/docs/plugins/steam-engine.rst b/docs/plugins/steam-engine.rst index 0fe245d63..e0f938915 100644 --- a/docs/plugins/steam-engine.rst +++ b/docs/plugins/steam-engine.rst @@ -1,10 +1,13 @@ steam-engine ============ -**Tags:** `tag/fort`, `tag/mod`, `tag/buildings` -Allow modded steam engine buildings to function. The steam-engine plugin detects -custom workshops with STEAM_ENGINE in their token, and turns them into real -steam engines! +.. dfhack-tool:: + :summary: Allow modded steam engine buildings to function. + :tags: fort mod buildings + :no-command: + +The steam-engine plugin detects custom workshops with the string +``STEAM_ENGINE`` in their token, and turns them into real steam engines! The plugin auto-enables itself when it detects the relevant tags in the world raws. It does not need to be enabled with the `enable` command. diff --git a/docs/plugins/stockflow.rst b/docs/plugins/stockflow.rst index 48647b869..81eab07ff 100644 --- a/docs/plugins/stockflow.rst +++ b/docs/plugins/stockflow.rst @@ -1,11 +1,13 @@ stockflow ========= -**Tags:** `tag/fort`, `tag/auto`, `tag/jobs`, `tag/stockpiles` -:dfhack-keybind:`stockflow` -Queue manager jobs based on free space in stockpiles. With this plugin, the -fortress bookkeeper can tally up free space in specific stockpiles and queue -jobs through the manager to produce items to fill the free space. +.. dfhack-tool:: + :summary: Queue manager jobs based on free space in stockpiles. + :tags: fort auto jobs stockpiles + +With this plugin, the fortress bookkeeper can tally up free space in specific +stockpiles and queue jobs through the manager to produce items to fill the free +space. When the plugin is enabled, the :kbd:`q` menu of each stockpile will have two new options: diff --git a/docs/plugins/stockpiles.rst b/docs/plugins/stockpiles.rst index 0c1000456..0e30b9dc7 100644 --- a/docs/plugins/stockpiles.rst +++ b/docs/plugins/stockpiles.rst @@ -2,14 +2,24 @@ stockpiles ========== -**Tags:** `tag/fort`, `tag/productivity`, `tag/design`, `tag/stockpiles` -:dfhack-keybind:`copystock` -:dfhack-keybind:`savestock` -:dfhack-keybind:`loadstock` - -Import and export stockpile settings. When the plugin is enabled, the :kbd:`q` -menu of each stockpile will have an option for saving or loading the stockpile -settings. See `gui/stockpiles` for an in-game interface. + +.. dfhack-tool:: + :summary: Import and export stockpile settings. + :tags: fort productivity design stockpiles + :no-command: + +.. dfhack-command:: copystock + :summary: Copies the configuration of the selected stockpile. + +.. dfhack-command:: savestock + :summary: Exports the configuration of the selected stockpile. + +.. dfhack-command:: loadstock + :summary: Imports the configuration of the selected stockpile. + +When the plugin is enabled, the :kbd:`q` menu of each stockpile will have an +option for saving or loading the stockpile settings. See `gui/stockpiles` for +an in-game interface. Usage: diff --git a/docs/plugins/stocks.rst b/docs/plugins/stocks.rst index 5506b1d28..e518fc1f1 100644 --- a/docs/plugins/stocks.rst +++ b/docs/plugins/stocks.rst @@ -1,10 +1,11 @@ stocks ====== -**Tags:** `tag/fort`, `tag/productivity`, `tag/interface` -:dfhack-keybind:`stocks` -Enhanced fortress stock management interface. When the plugin is enabled, two -new hotkeys become available: +.. dfhack-tool:: + :summary: Enhanced fortress stock management interface. + :tags: fort productivity interface + +When the plugin is enabled, two new hotkeys become available: * :kbd:`e` on the vanilla DF stocks screen (:kbd:`z` and then select Stocks) will launch the fortress-wide stock management screen. diff --git a/docs/plugins/stonesense.rst b/docs/plugins/stonesense.rst index 3bb271477..0315c92ed 100644 --- a/docs/plugins/stonesense.rst +++ b/docs/plugins/stonesense.rst @@ -1,10 +1,12 @@ stonesense ========== -**Tags:** `tag/adventure`, `tag/fort`, `tag/interface`, `tag/map` -:dfhack-keybind:`stonesense` -:dfhack-keybind:`ssense` -A 3D isometric visualizer that runs in a second window. +.. dfhack-tool:: + :summary: A 3D isometric visualizer. + :tags: adventure fort interface map + +.. dfhack-command:: ssense + :summary: An alias for stonesense. Usage: diff --git a/docs/plugins/strangemood.rst b/docs/plugins/strangemood.rst index 0198af136..8d1fc8081 100644 --- a/docs/plugins/strangemood.rst +++ b/docs/plugins/strangemood.rst @@ -1,9 +1,9 @@ strangemood =========== -**Tags:** `tag/fort`, `tag/armok`, `tag/units` -:dfhack-keybind:`strangemood` -Triggers a strange mood. +.. dfhack-tool:: + :summary: Trigger a strange mood. + :tags: fort armok units Usage:: diff --git a/docs/plugins/tailor.rst b/docs/plugins/tailor.rst index 93072fb1b..5da293fbf 100644 --- a/docs/plugins/tailor.rst +++ b/docs/plugins/tailor.rst @@ -1,13 +1,14 @@ tailor ====== -**Tags:** `tag/fort`, `tag/auto`, `tag/jobs` -:dfhack-keybind:`tailor` - -Automatically keep your dwarves in fresh clothing. Whenever the bookkeeper -updates stockpile records, this plugin will scan the fort. If there are -fresh cloths available, dwarves who are wearing tattered clothing will have -their rags confiscated (in the same manner as the `cleanowned` tool) so that -they'll reequip with replacement clothes. + +.. dfhack-tool:: + :summary: Automatically keep your dwarves in fresh clothing. + :tags: fort auto jobs + +Whenever the bookkeeper updates stockpile records, this plugin will scan the +fort. If there are fresh cloths available, dwarves who are wearing tattered +clothing will have their rags confiscated (in the same manner as the +`cleanowned` tool) so that they'll reequip with replacement clothes. If there are not enough clothes available, manager orders will be generated to manufacture some more. ``tailor`` will intelligently create orders using diff --git a/docs/plugins/tiletypes.rst b/docs/plugins/tiletypes.rst index 185f283db..ee3d4a02f 100644 --- a/docs/plugins/tiletypes.rst +++ b/docs/plugins/tiletypes.rst @@ -3,15 +3,23 @@ tiletypes ========= -**Tags:** `tag/adventure`, `tag/fort`, `tag/armok`, `tag/map` -:dfhack-keybind:`tiletypes` -:dfhack-keybind:`tiletypes-command` -:dfhack-keybind:`tiletypes-here` -:dfhack-keybind:`tiletypes-here-point` - -Paints tiles of specified types onto the map. You can use the `probe` command -to discover properties of existing tiles that you'd like to copy. If you -accidentally paint over a vein that you want back, `fixveins` may help. + +.. dfhack-tool:: + :summary: Paints tiles of specified types onto the map. + :tags: adventure fort armok map + +.. dfhack-command:: tiletypes-command + :summary: Run tiletypes commands. + +.. dfhack-command:: tiletypes-here + :summary: Paint map tiles starting from the cursor. + +.. dfhack-command:: tiletypes-here-point + :summary: Paint the map tile under the cursor. + +You can use the `probe` command to discover properties of existing tiles that +you'd like to copy. If you accidentally paint over a vein that you want back, +`fixveins` may help. The tool works with a brush, a filter, and a paint specification. The brush determines the shape of the area to affect, the filter selects which tiles to diff --git a/docs/plugins/title-folder.rst b/docs/plugins/title-folder.rst index beddfc9cb..56de7d769 100644 --- a/docs/plugins/title-folder.rst +++ b/docs/plugins/title-folder.rst @@ -1,8 +1,10 @@ title-folder ============= -**Tags:** `tag/system`, `tag/interface` -Displays the DF folder name in the window title bar. +.. dfhack-tool:: + :summary: Displays the DF folder name in the window title bar. + :tags: system interface + :no-command: Usage:: diff --git a/docs/plugins/title-version.rst b/docs/plugins/title-version.rst index d9d35a85f..f7fc238c7 100644 --- a/docs/plugins/title-version.rst +++ b/docs/plugins/title-version.rst @@ -1,8 +1,10 @@ title-version ============= -**Tags:** `tag/system`, `tag/interface` -Displays the DFHack version on DF's title screen. +.. dfhack-tool:: + :summary: Displays the DFHack version on DF's title screen. + :tags: system interface + :no-command: Usage:: diff --git a/docs/plugins/trackstop.rst b/docs/plugins/trackstop.rst index cf5a9853f..65aae2b7f 100644 --- a/docs/plugins/trackstop.rst +++ b/docs/plugins/trackstop.rst @@ -1,11 +1,15 @@ trackstop ========= -**Tags:** `tag/fort`, `tag/interface`, `tag/mod`, `tag/buildings` -Adds dynamic configuration options for track stops. When enabled, this plugin -adds a :kbd:`q` menu for track stops, which is completely blank in vanilla DF. -This allows you to view and/or change the track stop's friction and dump -direction settings, using the keybindings from the track stop building interface. +.. dfhack-tool:: + :summary: Add dynamic configuration options for track stops. + :tags: fort interface mod buildings + :no-command: + +When enabled, this plugin adds a :kbd:`q` menu for track stops, which is +completely blank in vanilla DF. This allows you to view and/or change the track +stop's friction and dump direction settings, using the keybindings from the +track stop building interface. Usage:: diff --git a/docs/plugins/tubefill.rst b/docs/plugins/tubefill.rst index 404a180b2..865e4341d 100644 --- a/docs/plugins/tubefill.rst +++ b/docs/plugins/tubefill.rst @@ -1,9 +1,11 @@ tubefill ======== -**Tags:** `tag/fort`, `tag/armok`, `tag/map` -:dfhack-keybind:`tubefill` -Replentishes mined-out adamantine. Veins that were hollow will be left alone. +.. dfhack-tool:: + :summary: Replentishes mined-out adamantine. + :tags: fort armok map + +Veins that were originally hollow will be left alone. Usage:: diff --git a/docs/plugins/tweak.rst b/docs/plugins/tweak.rst index 03489845e..71b564434 100644 --- a/docs/plugins/tweak.rst +++ b/docs/plugins/tweak.rst @@ -1,9 +1,9 @@ tweak ===== -**Tags:** `tag/adventure`, `tag/fort`, `tag/interface`, `tag/fps`, `tag/fix`, `tag/armok` -:dfhack-keybind:`tweak` -Contains various tweaks for minor bugs. +.. dfhack-tool:: + :summary: A collection of tweaks and bugfixes. + :tags: adventure fort interface fps fix armok Usage:: diff --git a/docs/plugins/workNow.rst b/docs/plugins/workNow.rst index 895556ce3..678649487 100644 --- a/docs/plugins/workNow.rst +++ b/docs/plugins/workNow.rst @@ -1,11 +1,13 @@ workNow ======= -**Tags:** `tag/fort`, `tag/auto`, `tag/jobs` -:dfhack-keybind:`workNow` -Reduce the time that dwarves idle after completing a job. After finishing a job, -dwarves will wander away for a while before picking up a new job. This plugin -will automatically poke the game to assign dwarves to new tasks. +.. dfhack-tool:: + :summary: Reduce the time that dwarves idle after completing a job. + :tags: fort auto jobs + +After finishing a job, dwarves will wander away for a while before picking up a +new job. This plugin will automatically poke the game to assign dwarves to new +tasks. Usage: diff --git a/docs/plugins/workflow.rst b/docs/plugins/workflow.rst index c2a9ea26a..db615c876 100644 --- a/docs/plugins/workflow.rst +++ b/docs/plugins/workflow.rst @@ -1,8 +1,12 @@ workflow ======== -**Tags:** `tag/fort`, `tag/auto`, `tag/jobs` -:dfhack-keybind:`workflow` -:dfhack-keybind:`fix-job-postings` + +.. dfhack-tool:: + :summary: Manage repeat jobs according to stock levels. + :tags: fort auto jobs + +.. dfhack-command:: fix-job-postings + :summary: Fixes crashes caused by old versions of workflow. Manage repeat jobs according to stock levels. `gui/workflow` provides a simple front-end integrated in the game UI. @@ -55,7 +59,7 @@ Usage: can be copied to a file, and then reloaded using the `script` built-in command. ``fix-job-postings [dry-run]`` - Fixes crashes caused the version of workflow released with DFHack + Fixes crashes caused by the version of workflow released with DFHack 0.40.24-r4. It will be run automatically if needed. If your save has never been run with this version, you will never need this command. Specify the ``dry-run`` keyword to see what this command would do without making any diff --git a/docs/plugins/xlsxreader.rst b/docs/plugins/xlsxreader.rst index 123d9920a..3d6cc0ac8 100644 --- a/docs/plugins/xlsxreader.rst +++ b/docs/plugins/xlsxreader.rst @@ -1,7 +1,9 @@ xlsxreader ========== -**Tags:** `tag/dev` -Provides a Lua API for reading xlsx files. +.. dfhack-tool:: + :summary: Provides a Lua API for reading xlsx files. + :tags: dev + :no-command: See `xlsxreader-api` for details. diff --git a/docs/plugins/zone.rst b/docs/plugins/zone.rst index 9aa34d746..bf9428a6c 100644 --- a/docs/plugins/zone.rst +++ b/docs/plugins/zone.rst @@ -1,9 +1,9 @@ zone ==== -**Tags:** `tag/fort`, `tag/productivity`, `tag/animals`, `tag/buildings` -:dfhack-keybind:`zone` -Manage activity zones, cages, and the animals therein. +.. dfhack-tool:: + :summary: Manage activity zones, cages, and the animals therein. + :tags: fort productivity animals buildings Usage: diff --git a/docs/sphinx_extensions/dfhack/tool_docs.py b/docs/sphinx_extensions/dfhack/tool_docs.py index ff4bfc9b1..a051b76af 100644 --- a/docs/sphinx_extensions/dfhack/tool_docs.py +++ b/docs/sphinx_extensions/dfhack/tool_docs.py @@ -117,6 +117,7 @@ class DFHackToolDirective(DFHackToolDirectiveBase): option_spec = { 'tags': dfhack.util.directive_arg_str_list, 'no-command': rst_directives.flag, + 'summary': rst_directives.unchanged, } def render_content(self) -> List[nodes.Node]: @@ -134,9 +135,12 @@ class DFHackToolDirective(DFHackToolDirectiveBase): ] tag_nodes.pop() - return [ + ret_nodes = [ nodes.paragraph('', '', *tag_nodes), ] + if 'no-command' in self.options: + ret_nodes += [nodes.inline(text=self.options.get('summary', ''))] + return ret_nodes def run(self): out = DFHackToolDirectiveBase.run(self) @@ -146,10 +150,15 @@ class DFHackToolDirective(DFHackToolDirectiveBase): class DFHackCommandDirective(DFHackToolDirectiveBase): + option_spec = { + 'summary': rst_directives.unchanged_required, + } + def render_content(self) -> List[nodes.Node]: command = self.get_name_or_docname() return [ self.make_labeled_paragraph('Command', command, content_class=nodes.literal), + nodes.inline(text=self.options.get('summary', '')), *render_dfhack_keybind(command), ]