MetzNet
/
dfhack
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update documentation documentation

develop
myk002 2022-09-12 14:15:46 -07:00 committed by Myk
parent dde56040c3
commit 0e30160c3c
2 changed files with 68 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

107
docs/Documentation.rst
Unescape Escape View File

@ -8,7 +8,7 @@ DFHack Documentation System
DFHack documentation, like the file you are reading now, is created as a set of DFHack documentation, like the file you are reading now, is created as a set of
``.rst`` files in `reStructuredText (reST) <https://www.sphinx-doc.org/rest.html>`_ ``.rst`` files in `reStructuredText (reST) <https://www.sphinx-doc.org/rest.html>`_
format. This is a documentation format common in the Python community. It is very format. This is a documentation format common in the Python community. It is very
similar in concept - and in syntax - to Markdown, as found on GitHub and many other similar in concept -- and in syntax -- to Markdown, as found on GitHub and many other
places. However it is more advanced than Markdown, with more features available when places. However it is more advanced than Markdown, with more features available when
compiled to HTML, such as automatic tables of contents, cross-linking, special compiled to HTML, such as automatic tables of contents, cross-linking, special
external links (forum, wiki, etc) and more. The documentation is compiled by a external links (forum, wiki, etc) and more. The documentation is compiled by a
@ -23,11 +23,13 @@ if you're changing them and want to see the changes reflected in your game.
You can also build the docs if you just want a local HTML- or text-rendered copy, though You can also build the docs if you just want a local HTML- or text-rendered copy, though
you can always read the `online version <https://dfhack.readthedocs.org>`_ too. you can always read the `online version <https://dfhack.readthedocs.org>`_ too.
The active development version of the documentation is tagged with ``latest`` and
is available `here <https://docs.dfhack.org/en/latest/index.html>`_
(Note that even if you do want a local copy, it is certainly not necessary to Note that even if you do want a local copy, it is certainly not necessary to
compile the documentation in order to read it. Like Markdown, reST documents are compile the documentation in order to read it. Like Markdown, reST documents are
designed to be just as readable in a plain-text editor as they are in HTML format. designed to be just as readable in a plain-text editor as they are in HTML format.
The main thing you lose in plain text format is hyperlinking.) The main thing you lose in plain text format is hyperlinking.
.. contents:: Contents .. contents:: Contents
:local: :local:
@ -42,19 +44,17 @@ location in ``hack/docs`` under the DF directory.
When writing documentation, remember that everything should be documented! If it's not When writing documentation, remember that everything should be documented! If it's not
clear *where* a particular thing should be documented, ask on Discord or in the DFHack clear *where* a particular thing should be documented, ask on Discord or in the DFHack
thread on Bay12 -- you'll not only be getting help, you'll also be providing valuable thread on Bay12 -- you'll not only be getting help, you'll also be providing valuable
feedback that makes it easier for future contributers to find documentation on how to feedback that makes it easier for future contributors to find documentation on how to
write the documentation! write the documentation!
Try to keep lines within 80-100 characters, so it's readable in plain text Try to keep lines within 80-100 characters so it's readable in plain text in the
in the terminal - Sphinx (our documentation system) will make sure terminal - Sphinx (our documentation system) will make sure paragraphs flow.
paragraphs flow.
Short descriptions Short descriptions
------------------ ------------------
Each command that a user can run, as well as every plugin that can be enabled for some Each command that a user can run -- as well as every plugin -- needs to have a
lasting effect, needs to have a short (~54 character) descriptive string associated with short (~54 character) descriptive string associated with it. This description text is:
it. This description text is:
- used in-game by the `ls` command and DFHack UI screens that list commands - used in-game by the `ls` command and DFHack UI screens that list commands
- used in the generated index entries in the HTML docs - used in the generated index entries in the HTML docs
@ -114,10 +114,9 @@ in a file named ``docs/gui/foobar.rst`` in the scripts repo. Similarly, a plugin
``foobaz`` should be documented in a file named ``docs/plugins/foobaz.rst`` in the dfhack repo. ``foobaz`` should be documented in a file named ``docs/plugins/foobaz.rst`` in the dfhack repo.
For plugins, all commands provided by that plugin should be documented in that same file. For plugins, all commands provided by that plugin should be documented in that same file.
Short descriptions (the ~54 character short help) are taken from the first "sentence" of Short descriptions (the ~54 character short help) for scripts and plugins are taken from
the help text for scripts and plugins that can be enabled. This means that the help should the ``summary`` attribute of the ``dfhack-tool`` directive that each tool help document must
begin with a sentence fragment that begins with a capital letter and ends in a full stop have (see the `Header format`_ section below). Please make this brief but descriptive!
(``.``). Please make this brief but descriptive!
Short descriptions for commands provided by plugins are taken from the ``description`` Short descriptions for commands provided by plugins are taken from the ``description``
parameter passed to the ``PluginCommand`` constructor used when the command is registered parameter passed to the ``PluginCommand`` constructor used when the command is registered
@ -127,11 +126,11 @@ Header format
------------- -------------
The docs **must** begin with a heading which exactly matches the script or plugin name, underlined The docs **must** begin with a heading which exactly matches the script or plugin name, underlined
with ``=====`` to the same length. This should be followed by a ``.. dfhack-tool:`` directive with with ``=====`` to the same length. This must be followed by a ``.. dfhack-tool:`` directive with
at least the following parameters: at least the following parameters:
* ``:summary:`` - a short, single-sentence description of the tool * ``:summary:`` - a short, single-sentence description of the tool
* ``:tags:`` - a space-separated list of tags that apply to the tool * ``:tags:`` - a space-separated list of `tags <tag-list>` that apply to the tool
By default, ``dfhack-tool`` generates both a description of a tool and a command By default, ``dfhack-tool`` generates both a description of a tool and a command
with the same name. For tools (specifically plugins) that do not provide exactly with the same name. For tools (specifically plugins) that do not provide exactly
@ -231,6 +230,7 @@ angle brackets (``<`` and ``>``). Optional elements are enclosed in square brack
If the command takes an arbitrary number of elements, use ``...``, for example:: If the command takes an arbitrary number of elements, use ``...``, for example::
prioritize [<options>] <job type> [<job type> ...] prioritize [<options>] <job type> [<job type> ...]
quickfort <command>[,<command>...] <list_id>[,<list_id>...] [<options>]
Examples Examples
-------- --------
@ -240,11 +240,11 @@ Otherwise, please consider adding a section that shows some real, practical usag
many users, this will be the **only** section they will read. It is so important that it is a good many users, this will be the **only** section they will read. It is so important that it is a good
idea to include the ``Examples`` section **before** you describe any extended options your command idea to include the ``Examples`` section **before** you describe any extended options your command
might take. Write examples for what you expect the popular use cases will be. Also be sure to write might take. Write examples for what you expect the popular use cases will be. Also be sure to write
examples showing specific, practical values being used for any parameter that takes a value. examples showing specific, practical values being used for any parameter that takes a value or has
tricky formatting.
Examples should go in their own subheading with a single dash underline (``--------``). The examples Examples should go in their own subheading. The examples themselves should be organized as in
themselves should be organized in a list, the same as in option 2 for Usage above. Here is an option 2 for Usage above. Here is an example ``Examples`` section::
example Examples section::
Examples Examples
-------- --------
@ -258,7 +258,7 @@ example Examples section::
Options Options
------- -------
The options header should follow the examples, with each option in the same list format as the The options header should follow the examples, with each option in the same format as the
examples:: examples::
Options Options
@ -285,7 +285,8 @@ scripts and plugins can use a different mechanism to at least make their help te
in-game. in-game.
Note that since help text for external scripts and plugins is not rendered by Sphinx, Note that since help text for external scripts and plugins is not rendered by Sphinx,
it should be written in plain text. Any reStructuredText markup will not be processed. it should be written in plain text. Any reStructuredText markup will not be processed and,
if present, will be shown verbatim to the player (which is probably not what you want).
For external scripts, the short description comes from a comment on the first line For external scripts, the short description comes from a comment on the first line
(the comment marker and extra whitespace is stripped). For Lua, this would look like: (the comment marker and extra whitespace is stripped). For Lua, this would look like:
@ -310,27 +311,33 @@ entire script header::
-- [====[ -- [====[
gui/adv-inventory gui/adv-inventory
================= =================
Tags: adventure, items
Tags: adventure | items
Allows you to quickly move items between containers. This Allows you to quickly move items between containers. This
includes yourself and any followers you have. includes yourself and any followers you have.
Usage: Usage
-----
gui/adv-inventory [<options>] gui/adv-inventory [<options>]
Examples: Examples
--------
gui/adv-inventory gui/adv-inventory
Opens the GUI with nothing preselected Opens the GUI with nothing preselected
gui/adv-inventory take-all gui/adv-inventory take-all
Opens the GUI with all container items already selected and Opens the GUI with all container items already selected and
ready to move into the adventurer's inventory. ready to move into the adventurer's inventory.
Options: Options
-------
take-all take-all
Starts the GUI with container items pre-selected Starts the GUI with container items pre-selected
give-all give-all
Starts the GUI with your own items pre-selected Starts the GUI with your own items pre-selected
]====] ]====]
@ -347,10 +354,10 @@ Required dependencies
.. highlight:: shell .. highlight:: shell
In order to build the documentation, you must have Python with Sphinx In order to build the documentation, you must have Python with Sphinx
version |sphinx_min_version| or later. Python 3 is recommended. version |sphinx_min_version| or later and Python 3.
When installing Sphinx from OS package managers, be aware that there is When installing Sphinx from OS package managers, be aware that there is
another program called Sphinx, completely unrelated to documentation management. another program called "Sphinx", completely unrelated to documentation management.
Be sure you are installing the right Sphinx; it may be called ``python-sphinx``, Be sure you are installing the right Sphinx; it may be called ``python-sphinx``,
for example. To avoid doubt, ``pip`` can be used instead as detailed below. for example. To avoid doubt, ``pip`` can be used instead as detailed below.
@ -364,13 +371,12 @@ For more detailed platform-specific instructions, see the sections below:
:local: :local:
:backlinks: none :backlinks: none
Linux Linux
----- -----
Most Linux distributions will include Python by default. If not, start by Most Linux distributions will include Python by default. If not, start by
installing Python (preferably Python 3). On Debian-based distros:: installing Python 3. On Debian-based distros::
sudo apt install python3 sudo apt install python3
Check your package manager to see if Sphinx |sphinx_min_version| or later is Check your package manager to see if Sphinx |sphinx_min_version| or later is
available. On Debian-based distros, this package is named ``python3-sphinx``. available. On Debian-based distros, this package is named ``python3-sphinx``.
@ -379,11 +385,11 @@ want to use a newer Sphinx version (which may result in faster builds), you
can install Sphinx through the ``pip`` package manager instead. On Debian-based can install Sphinx through the ``pip`` package manager instead. On Debian-based
distros, you can install pip with:: distros, you can install pip with::
sudo apt install python3-pip sudo apt install python3-pip
Once pip is available, you can then install Sphinx with:: Once pip is available, you can then install Sphinx with::
pip3 install sphinx pip3 install sphinx
If you run this as an unprivileged user, it may install a local copy of Sphinx If you run this as an unprivileged user, it may install a local copy of Sphinx
for your user only. The ``sphinx-build`` executable will typically end up in for your user only. The ``sphinx-build`` executable will typically end up in
@ -398,34 +404,23 @@ macOS has Python 2.7 installed by default, but it does not have the pip package
You can install Homebrew's Python 3, which includes pip, and then install the You can install Homebrew's Python 3, which includes pip, and then install the
latest Sphinx using pip:: latest Sphinx using pip::
brew install python3 brew install python3
pip3 install sphinx pip3 install sphinx
Alternatively, you can simply install Sphinx directly from Homebrew::
brew install sphinx-doc
This will install Sphinx for macOS's system Python 2.7, without needing pip.
Either method works; if you plan to use Python for other purposes, it might best
to install Homebrew's Python 3 so that you have the latest Python as well as pip.
If not, just installing sphinx-doc for macOS's system Python 2.7 is fine.
Windows Windows
------- -------
Python for Windows can be downloaded `from python.org <https://www.python.org/downloads/>`_. Python for Windows can be downloaded `from python.org <https://www.python.org/downloads/>`_.
The latest version of Python 3 is recommended, as it includes pip already. The latest version of Python 3 includes pip already.
You can also install Python and pip through the Chocolatey package manager. You can also install Python and pip through the Chocolatey package manager.
After installing Chocolatey as outlined in the `Windows compilation instructions <compile-windows>`, After installing Chocolatey as outlined in the `Windows compilation instructions <compile-windows>`,
run the following command from an elevated (admin) command prompt (e.g. ``cmd.exe``):: run the following command from an elevated (admin) command prompt (e.g. ``cmd.exe``)::
choco install python pip -y choco install python pip -y
Once you have pip available, you can install Sphinx with the following command:: Once you have pip available, you can install Sphinx with the following command::
pip install sphinx pip install sphinx
Note that this may require opening a new (admin) command prompt if you just Note that this may require opening a new (admin) command prompt if you just
installed pip from the same command prompt. installed pip from the same command prompt.
@ -465,8 +460,9 @@ ways to do this:
By default, both HTML and text docs are built by CMake. The generated By default, both HTML and text docs are built by CMake. The generated
documentation is stored in ``docs/html`` and ``docs/text`` (respectively) in the documentation is stored in ``docs/html`` and ``docs/text`` (respectively) in the
root DFHack folder, and will be installed to ``hack/docs`` when you install root DFHack folder, and they will both be installed to ``hack/docs`` when you
DFHack. install DFHack. The html and txt files will intermingle, but will not interfere
with one another.
Running Sphinx manually Running Sphinx manually
----------------------- -----------------------
@ -474,8 +470,8 @@ Running Sphinx manually
You can also build the documentation without running CMake - this is faster if You can also build the documentation without running CMake - this is faster if
you only want to rebuild the documentation regardless of any code changes. The you only want to rebuild the documentation regardless of any code changes. The
``docs/build.py`` script will build the documentation in any specified formats ``docs/build.py`` script will build the documentation in any specified formats
(HTML only by default) using essentially the same command that CMake runs when (HTML only by default) using the same command that CMake runs when building the
building the docs. Run the script with ``--help`` to see additional options. docs. Run the script with ``--help`` to see additional options.
Examples: Examples:
@ -501,7 +497,9 @@ or, to build plain-text output::
Sphinx has many options to enable clean builds, parallel builds, logging, and Sphinx has many options to enable clean builds, parallel builds, logging, and
more - run ``sphinx-build --help`` for details. If you specify a different more - run ``sphinx-build --help`` for details. If you specify a different
output path, be warned that Sphinx may overwrite existing files in the output output path, be warned that Sphinx may overwrite existing files in the output
folder. folder. Also be aware that when running ``sphinx-build`` directly, the
``docs/html`` folder may be polluted with intermediate build files that normally
get written in the cmake ``build`` directory.
Building a PDF version Building a PDF version
---------------------- ----------------------
@ -546,7 +544,6 @@ closest stable release after 0.44.05-alpha1). An entry listed under a stable
release like "0.44.05-r1" in changelog.txt will be listed under that release in release like "0.44.05-r1" in changelog.txt will be listed under that release in
both the stable changelog and the development changelog. both the stable changelog and the development changelog.
Changelog syntax Changelog syntax
---------------- ----------------

38
docs/Lua API.rst
Unescape Escape View File

@ -5096,9 +5096,8 @@ the extension omitted. For example:
* :file:`hack/scripts/gui/teleport.lua` is invoked as ``gui/teleport`` * :file:`hack/scripts/gui/teleport.lua` is invoked as ``gui/teleport``
.. note:: .. note::
Scripts placed in subdirectories can be run as described above, but are not In general, scripts should be placed in subfolders in the following
listed by the `ls` command unless ``-a`` is specified. In general, scripts situations:
should be placed in subfolders in the following situations:
* ``devel``: scripts that are intended exclusively for DFHack development, * ``devel``: scripts that are intended exclusively for DFHack development,
including examples, or scripts that are experimental and unstable including examples, or scripts that are experimental and unstable
@ -5116,16 +5115,12 @@ folders can be added (for example, a copy of the
:source-scripts:`scripts repository <>` for local development). See :source-scripts:`scripts repository <>` for local development). See
`script-paths` for more information on how to configure this behavior. `script-paths` for more information on how to configure this behavior.
If the first line of the script is a one-line comment (starting with ``--``),
the content of the comment is used by the built-in ``ls`` and ``help`` commands.
Such a comment is required for every script in the official DFHack repository.
Scripts are read from disk when run for the first time, or if they have changed Scripts are read from disk when run for the first time, or if they have changed
since the last time they were run. since the last time they were run.
Each script has an isolated environment where global variables set by the script Each script has an isolated environment where global variables set by the script
are stored. Values of globals persist across script runs in the same DF session. are stored. Values of globals persist across script runs in the same DF session.
See `devel/lua-example` for an example of this behavior. Note that local See `devel/lua-example` for an example of this behavior. Note that ``local``
variables do *not* persist. variables do *not* persist.
Arguments are passed in to the scripts via the ``...`` built-in quasi-variable; Arguments are passed in to the scripts via the ``...`` built-in quasi-variable;
@ -5147,9 +5142,9 @@ General script API
* ``dfhack.run_script(name[,args...])`` * ``dfhack.run_script(name[,args...])``
Run a Lua script in hack/scripts/, as if it were started from the DFHack Run a Lua script in :file:`hack/scripts/`, as if it were started from the
command-line. The ``name`` argument should be the name of the script without DFHack command-line. The ``name`` argument should be the name of the script
its extension, as it would be used on the command line. without its extension, as it would be used on the command line.
Example: Example:
@ -5169,10 +5164,10 @@ General script API
* ``dfhack.script_help([name, [extension]])`` * ``dfhack.script_help([name, [extension]])``
Returns the contents of the embedded documentation of the specified script. Returns the contents of the rendered (or embedded) `documentation` for the
``extension`` defaults to "lua", and ``name`` defaults to the name of the specified script. ``extension`` defaults to "lua", and ``name`` defaults to
script where this function was called. For example, the following can be used the name of the script where this function was called. For example, the
to print the current script's help text:: following can be used to print the current script's help text::
local args = {...} local args = {...}
if args[1] == 'help' then if args[1] == 'help' then
@ -5180,7 +5175,6 @@ General script API
return return
end end
Importing scripts Importing scripts
================= =================
@ -5234,12 +5228,12 @@ Importing scripts
.. warning:: .. warning::
Avoid caching the table returned by ``reqscript()`` beyond storing it in Avoid caching the table returned by ``reqscript()`` beyond storing it in
a local or global variable as in the example above. ``reqscript()`` is fast a local variable as in the example above. ``reqscript()`` is fast for
for scripts that have previously been loaded and haven't changed. If you scripts that have previously been loaded and haven't changed. If you retain
retain a reference to a table returned by an old ``reqscript()`` call, this a reference to a table returned by an old ``reqscript()`` call, this may
may lead to unintended behavior if the location of the script changes lead to unintended behavior if the location of the script changes (e.g. if a
(e.g. if a save is loaded or unloaded, or if a `script path <script-paths>` save is loaded or unloaded, or if a `script path <script-paths>` is added in
is added in some other way). some other way).
.. admonition:: Tip .. admonition:: Tip