enable index building and update builtin docs

conf.py

@@ -346,8 +346,8 @@ html_sidebars = {
 # If false, no module index is generated.
 html_domain_indices = False
 
-# If false, no index is generated.
+# If false, no genindex.html is generated.
-html_use_index = False
+html_use_index = True
 
 html_css_files = [
     'dfhack.css',

docs/builtins/alias.rst

@@ -4,10 +4,11 @@ alias
 Tags: system
 :dfhack-keybind:`alias`
 
-Configure helper aliases for other DFHack commands. Aliases are resolved
+:index:`Configure helper aliases for other DFHack commands.
-immediately after built-in commands, which means that an alias cannot override
+<alias; Configure helper aliases for other DFHack commands.>` Aliases are
-a built-in command, but can override a command implemented by a plugin or
+resolved immediately after built-in commands, which means that an alias cannot
-script.
+override a built-in command, but can override a command implemented by a plugin
+or script.
 
 Usage:
 

docs/builtins/clear.rst

@@ -1,7 +0,0 @@
-clear
-=====
-
-Tags: system
-:dfhack-keybind:`clear`
-
-Clear the terminal screen. This command is an alias for `cls`.

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
+:index:`Clear the terminal screen. <cls; Clear the terminal screen.>` Can also
-command does not delete command history. It just clears the text on the screen.
+be invoked as ``clear``. Note that this command does not delete command history.
+It just clears the text on the screen.

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::
 

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.>`

docs/builtins/dir.rst

@@ -1,7 +0,0 @@
-dir
-===
-
-Tags: system
-:dfhack-keybind:`dir`
-
-List available DFHack commands. This is an alias of the `ls` command.

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`
+:index:`Deactivate a DFHack tool that has some persistent effect.
-command for more info.
+<disable; Deactivate a DFHack tool that has some persistent effect.>` See the
+`enable` command for more info.
 
 Usage::
 

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
+:index:`Activate a DFHack tool that has some persistent effect.
-can be in a distinct enabled or disabled state. Some of them activate and
+<enable; Activate a DFHack tool that has some persistent effect.>` Many plugins
-deactivate automatically depending on the contents of the world raws. Others
+and scripts can be in a distinct enabled or disabled state. Some of them
-store their state in world data. However a number of them have to be enabled
+activate and deactivate automatically depending on the contents of the world
-globally, and the init file is the right place to do it.
+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

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
+:index:`Forces DF to pause. <fpause; Forces DF to pause.>` This is useful when
-control of the game.
+your FPS drops below 1 and you lose control of the game.
 
 Usage::
 

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::
 

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`.
 

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
+:index:`Create hotkeys that will run DFHack commands.
-used at any time from the console, but bindings are not remembered between runs
+<keybinding; Create hotkeys that will run DFHack commands.>` Like any other
-of the game unless re-created in `dfhack.init`.
+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:
 

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
+:index:`Gracefully stops any currently-running Lua scripts.
-a misbehaving script that appears to be stuck.
+<kill-lua; Gracefully stops any currently-running Lua scripts.>` Use this
+command to stop a misbehaving script that appears to be stuck.
 
 Usage::
 

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
+:index:`Load and register a plugin library.
-actions.
+<load; Load and register a plugin library.>` Also see `unload` and `reload` for
+related actions.
 
 Usage::
 

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
+:index:`List available DFHack commands. <ls; List available DFHack commands.>`
-is associated with a list of tags. You can filter the listed commands by a tag
+In order to group related commands, each command is associated with a list of
-or a substring of the command name. The `dir` command is an alias of this
+tags. You can filter the listed commands by a tag or a substring of the
-command.
+command name. Can also be invoked as ``dir``.
 
 Usage:
 

docs/builtins/man.rst

@@ -1,7 +0,0 @@
-man
-===
-
-Tags: system
-:dfhack-keybind:`man`
-
-An alias for the `help` command.

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:
 

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
+:index:`Reload a loaded plugin. <reload; Reload a loaded plugin.>` Developers
-are actively modifying. Also see `load` and `unload` for related actions.
+use this command to reload a plugin that they are actively modifying. Also see
+`load` and `unload` for related actions.
 
 Usage::
 

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
+:index:`Run commands when game state changes occur.
-`init-files` but is slightly more flexible since it can be set dynamically.
+<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:
 

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
+:index:`Executes a batch file of DFHack commands.
-line as a DFHack command as if it had been typed in by the user - treating the
+<script; Executes a batch file of DFHack commands.>` It reads a text file and
-input like `an init file <init-files>`.
+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``.

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
+:index:`Unhides the DFHack terminal window.
-`hide` and you want it back. Since the terminal window won't be available to run
+<show; Unhides the DFHack terminal window.>` Useful if you have hidden the
-this command, you'll need to use it from a `keybinding` set beforehand or the
+terminal with `hide` and you want it back. Since the terminal window won't be
-in-game `command-prompt`.
+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.
 

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
+:index:`List the strings that DFHack tools can be tagged with.
-related tools by passing the tag name to the `ls` command.
+<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::
 

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
+:index:`Describes how a command is implemented.
-plugins, scripts, or by the core library itself. The ``type`` command can tell
+<type; Describes how a command is implemented.>` DFHack commands can be provided
-you which is the source of a particular command.
+by plugins, scripts, or by the core library itself. The ``type`` command can
+tell you which is the source of a particular command.
 
 Usage::
 

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::