enable index building and update builtin docs

myk002 · myk002 · commit b3679bef2599 · 2022-07-21T23:21:56.000-07:00
diff --git a/conf.py b/conf.py
@@ -346,8 +346,8 @@ def get_version():
 # If false, no module index is generated.
 html_domain_indices = False
 
-# If false, no index is generated.
-html_use_index = False
+# If false, no genindex.html is generated.
+html_use_index = True
 
 html_css_files = [
     'dfhack.css',
diff --git a/docs/builtins/alias.rst b/docs/builtins/alias.rst
@@ -4,10 +4,11 @@ alias
 Tags: system
 :dfhack-keybind:`alias`
 
-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.
+:index:`Configure helper aliases for other DFHack commands.
+<alias; 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.
 
 Usage:
 
diff --git a/docs/builtins/clear.rst b/docs/builtins/clear.rst
diff --git a/docs/builtins/cls.rst b/docs/builtins/cls.rst
@@ -4,5 +4,6 @@ cls
 Tags: system
 :dfhack-keybind:`cls`
 
-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.
+:index:`Clear the terminal screen. <cls; 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.
diff --git a/docs/builtins/devel/dump-rpc.rst b/docs/builtins/devel/dump-rpc.rst
@@ -4,7 +4,8 @@ devel/dump-rpc
 Tags: system
 :dfhack-keybind:`devel/dump-rpc`
 
-Writes RPC endpoint information to the specified file.
+:index:`Writes RPC endpoint information to the specified file.
+<devel/dump-rpc; Writes RPC endpoint information to the specified file.>`
 
 Usage::
 
diff --git a/docs/builtins/die.rst b/docs/builtins/die.rst
@@ -4,4 +4,5 @@ die
 Tags: system
 :dfhack-keybind:`die`
 
-Instantly exits DF without saving.
+:index:`Instantly exits DF without saving.
+<die; Instantly exits DF without saving.>`
diff --git a/docs/builtins/dir.rst b/docs/builtins/dir.rst
diff --git a/docs/builtins/disable.rst b/docs/builtins/disable.rst
@@ -4,8 +4,9 @@ disable
 Tags: system
 :dfhack-keybind:`disable`
 
-Deactivate a DFHack tool that has some persistent effect. See the `enable`
-command for more info.
+:index:`Deactivate a DFHack tool that has some persistent effect.
+<disable; Deactivate a DFHack tool that has some persistent effect.>` See the
+`enable` command for more info.
 
 Usage::
 
diff --git a/docs/builtins/enable.rst b/docs/builtins/enable.rst
@@ -4,11 +4,12 @@ enable
 Tags: system
 :dfhack-keybind:`enable`
 
-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.
+:index:`Activate a DFHack tool that has some persistent effect.
+<enable; 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.
 
 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
@@ -4,8 +4,8 @@ fpause
 Tags: system
 :dfhack-keybind:`fpause`
 
-Forces DF to pause. This is useful when your FPS drops below 1 and you lose
-control of the game.
+:index:`Forces DF to pause. <fpause; Forces DF to pause.>` 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
@@ -4,7 +4,9 @@ help
 Tags: system
 :dfhack-keybind:`help`
 
-Display help about a command or plugin.
+:index:`Display help about a command or plugin.
+<help; Display help about a command or plugin.>` Can also be invoked as ``?``
+or ``man`` (short for "manual").
 
 Usage::
 
diff --git a/docs/builtins/hide.rst b/docs/builtins/hide.rst
@@ -4,7 +4,8 @@ hide
 Tags: system
 :dfhack-keybind:`hide`
 
-Hides the DFHack terminal window. You can show it again with the `show`
+:index:`Hides the DFHack terminal window.
+<hide; Hides 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`.
 
diff --git a/docs/builtins/keybinding.rst b/docs/builtins/keybinding.rst
@@ -4,12 +4,13 @@ keybinding
 Tags: system
 :dfhack-keybind:`keybinding`
 
-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`.
+:index:`Create hotkeys that will run DFHack commands.
+<keybinding; 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`.
 
 Hotkeys can be any combinations of Ctrl/Alt/Shift with A-Z, 0-9, F1-F12, or
-``\```.
+``\``` (the key below the ``Esc`` key.
 
 Usage:
 
diff --git a/docs/builtins/kill-lua.rst b/docs/builtins/kill-lua.rst
@@ -4,8 +4,9 @@ kill-lua
 Tags: system
 :dfhack-keybind:`kill-lua`
 
-Gracefully stops any currently-running Lua scripts. Use this command to stop
-a misbehaving script that appears to be stuck.
+:index:`Gracefully stops any currently-running Lua scripts.
+<kill-lua; Gracefully stops any currently-running Lua scripts.>` 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
@@ -4,8 +4,9 @@ load
 Tags: system
 :dfhack-keybind:`load`
 
-Load and register a plugin library. Also see `unload` and `reload` for related
-actions.
+:index:`Load and register a plugin library.
+<load; Load and register a plugin library.>` Also see `unload` and `reload` for
+related actions.
 
 Usage::
 
diff --git a/docs/builtins/ls.rst b/docs/builtins/ls.rst
@@ -4,10 +4,10 @@ ls
 Tags: system
 :dfhack-keybind:`ls`
 
-List available DFHack commands. 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. The `dir` command is an alias of this
-command.
+:index:`List available DFHack commands. <ls; List available DFHack commands.>`
+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``.
 
 Usage:
 
diff --git a/docs/builtins/man.rst b/docs/builtins/man.rst
diff --git a/docs/builtins/plug.rst b/docs/builtins/plug.rst
@@ -4,7 +4,8 @@ plug
 Tags: system
 :dfhack-keybind:`plug`
 
-Lists available plugins and whether they are enabled.
+:index:`Lists available plugins and whether they are enabled.
+<plug; Lists available plugins and whether they are enabled.>`
 
 Usage:
 
diff --git a/docs/builtins/reload.rst b/docs/builtins/reload.rst
@@ -4,8 +4,9 @@ reload
 Tags: system
 :dfhack-keybind:`reload`
 
-Reload a loaded plugin. Developer use this command to reload a plugin that they
-are actively modifying. Also see `load` and `unload` for related actions.
+:index:`Reload a loaded plugin. <reload; 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.
 
 Usage::
 
diff --git a/docs/builtins/sc-script.rst b/docs/builtins/sc-script.rst
@@ -4,8 +4,10 @@ sc-script
 Tags: system
 :dfhack-keybind:`sc-script`
 
-Runs 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.
+:index:`Run commands when game state changes occur.
+<sc-script; 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.
 
 Usage:
 
diff --git a/docs/builtins/script.rst b/docs/builtins/script.rst
@@ -4,9 +4,10 @@ script
 Tags: system
 :dfhack-keybind:`script`
 
-Executes 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 <init-files>`.
+:index:`Executes a batch file of DFHack commands.
+<script; Executes 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 <init-files>`.
 
 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
@@ -4,10 +4,11 @@ show
 Tags: system
 :dfhack-keybind:`show`
 
-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`.
+:index:`Unhides the DFHack terminal window.
+<show; 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`.
 
 Only available on Windows.
 
diff --git a/docs/builtins/tags.rst b/docs/builtins/tags.rst
@@ -4,8 +4,9 @@ tags
 Tags: system
 :dfhack-keybind:`tags`
 
-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.
+:index:`List the strings that DFHack tools can be tagged with.
+<tags; 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.
 
 Usage::
 
diff --git a/docs/builtins/type.rst b/docs/builtins/type.rst
@@ -4,9 +4,10 @@ type
 Tags: system
 :dfhack-keybind:`type`
 
-Describes 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.
+:index:`Describes how a command is implemented.
+<type; Describes 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.
 
 Usage::
 
diff --git a/docs/builtins/unload.rst b/docs/builtins/unload.rst
@@ -4,7 +4,8 @@ unload
 Tags: system
 :dfhack-keybind:`unload`
 
-Unload a plugin from memory. Also see `load` and `reload` for related actions.
+:index:`Unload a plugin from memory. <unload; Unload a plugin from memory.>`
+Also see `load` and `reload` for related actions.
 
 Usage::
 
