From 62523bdcb1a2da3083b219ef5d320d5f7f828a00 Mon Sep 17 00:00:00 2001 From: myk002 Date: Sat, 23 Jul 2022 15:13:11 -0700 Subject: [PATCH] update documentation for the documentation --- docs/Documentation.rst | 304 ++++++++++++++++++++++++++++++----------- 1 file changed, 225 insertions(+), 79 deletions(-) diff --git a/docs/Documentation.rst b/docs/Documentation.rst index c035a0366..6be4de37f 100644 --- a/docs/Documentation.rst +++ b/docs/Documentation.rst @@ -14,11 +14,15 @@ 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 Python tool, `Sphinx `_. -The DFHack build process will compile the documentation, but this is disabled -by default due to the additional Python and Sphinx requirements. You typically -only need to build the docs if you're changing them, or perhaps -if you want a local HTML copy; otherwise, you can read an -`online version hosted by ReadTheDocs `_. +The DFHack build process will compile and install the documentation so it can be +displayed in-game by the `help` and `ls` commands (and any other command or GUI that +displays help text), but this is disabled by default due to the additional Python and +Sphinx requirements. If you already have a version of the docs installed (say from a +downloaded release binary), then you only need to build the docs 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 always read the `online version `_. (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 @@ -28,6 +32,63 @@ The main thing you lose in plain text format is hyperlinking.) .. contents:: Contents :local: +Concepts and general guidance +============================= + +The source ``.rst`` files are compiled to HTML for viewing in a browser and to text +format for viewing in-game. For in-game help, the help text is read from its installed +location in ``hack/docs`` under the DF directory for in-game display. + +Remember, everything should be documented! If it's not clear *where* a particular thing +should be documented, ask on Discord or in the DFHack thread on Bay12 -- as well as +getting help, you'll be providing valuable feedback that makes it easier for future readers! + +Try to keep lines within 80-100 characters, so it's readable in plain text +in the terminal - Sphinx (our documentation system) will make sure +paragraphs flow. + +Short descriptions +------------------ + +Each command that a user can run, as well as every plugin that can be enabled for some +lasting effect, needs to have a short (~54 character) descriptive string associated with +it. This description text is: + +- used in-game by the `ls` command and DFHack UI screens that list commands +- used in the generated index entries in the HTML docs + +Tags +---- + +To make it easier for players to find related commands, all plugins and commands are marked +with relevant tags. These are used to compile indices and generate cross-links between the +commands, both in the HTML documents and in-game. See the list of available tags +`here ` and think about which categories your new tools belongs in. + +Links +----- + +If it would be helpful to mention another DFHack command, don't just type the +name - add a hyperlink! Specify the link target in backticks, and it will be +replaced with the corresponding title and linked: e.g. ```autolabor``` +=> `autolabor`. Scripts and plugins have link targets that match their names +created for you automatically. + +If you want to link to a heading in your own page, you can specifiy it like this:: + + `Heading text exactly as written`_ + +Note that the DFHack documentation is configured so that single backticks (with +no prefix or suffix) produce links to internal link targets, such as the +``autolabor`` target shown above. This is different from the reStructuredText +default behavior of rendering such text in italics (as a reference to a title). +For alternative link behaviors, see: + +- `The reStructuredText documentation on roles `__ +- `The reStructuredText documentation on external links `__ +- `The Sphinx documentation on roles `__ + - ``:doc:`` is useful for linking to another document outside of DFHack. + .. _docs-standards: Documentation standards @@ -38,106 +99,191 @@ there are a few important standards for completeness and consistent style. Trea this section as a guide rather than iron law, match the surrounding text, and you'll be fine. -Command documentation ---------------------- +Where do I add the help text? +----------------------------- -Each command should have a short (~54 character) help string, which is shown -by the `ls` command. For scripts, this is a comment on the first line -(the comment marker and whitespace is stripped). For plugins it's the second -argument to ``PluginCommand``. Please make this brief but descriptive! +For scripts and plugins that are distributed as part of DFHack, documentation files +should be added to the :source-scripts:`docs` and :source:`docs/plugins` directories, +respectively, in a file named after the script or plugin. For example, a script named +``gui/foobar.lua`` (which provides the ``gui/foobar`` command) should be documented +in a file named ``docs/gui/foobar.rst`` in the scripts repo. Similarly, a plugin named +``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. -Everything should be documented! If it's not clear *where* a particular -thing should be documented, ask on IRC or in the DFHack thread on Bay12 - -as well as getting help, you'll be providing valuable feedback that -makes it easier for future readers! +Short descriptions (the ~54 character short help) are taken from the first "sentence" of +the help text for scripts and plugins that can be enabled. This means that the help should +begin with a sentence fragment that begins with a capital letter and ends in a full stop +(``.``). Please make this brief but descriptive! -Scripts can use a custom autodoc function, based on the Sphinx ``include`` -directive - anything between the tokens is copied into the appropriate scripts -documentation page. For Ruby, we follow the built-in docstring convention -(``=begin`` and ``=end``). For Lua, the tokens are ``[====[`` and ``]====]`` -- ordinary multi-line strings. It is highly encouraged to reuse this string -as the in-console documentation by (e.g.) printing it when a ``-help`` argument -is given. +Short descriptions for commands provided by plugins are taken from the ``description`` +parameter passed to the ``PluginCommand`` constructor used when the command is registered +in the plugin source file. -The docs **must** have a heading which exactly matches the command, underlined -with ``=====`` to the same length. For example, a lua file would have: - -.. code-block:: lua +Header format +------------- - local helpstr = [====[ +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 ``Tags:`` line with +comma-separated links to the tag indices, and then a ``:dfhack-keybind:`commandname``` line for +each command provided by the script or plugin. For scripts, this will just be the script name. +Plugins that do not provide commands (i.e. they can just be enabled for some persistent effect or +they just export functionality via a Lua API) don't need any ``:dfhack-keybind:`` lines at all. +The first line of the text should then be the short description that will be used for the script +or plugin. For example, documentation for the ``build-now`` script might look like: - add-thought - =========== - Adds a thought or emotion to the selected unit. Can be used by other scripts, - or the gui invoked by running ``add-thought gui`` with a unit selected. +.. code-block:: rst - ]====] + build-now + ========= + Tags: `tag/fort`, `tag/buildings` + :dfhack-keybind:`build-now` + Instantly completes unsuspended building jobs. By default, all constructions + and buildings on the map are completed, but the area of effect is configurable. -.. highlight:: rst +Usage help +---------- -Where the heading for a section is also the name of a command, the spelling -and case should exactly match the command to enter in the DFHack command line. +The first section after the header and introductory text should be the usage block. You can +choose between two formats, based on whatever is cleaner or clearer for your syntax. The first +option is to show usage formats together, with an explanation following the block:: -Try to keep lines within 80-100 characters, so it's readable in plain text -in the terminal - Sphinx (our documentation system) will make sure -paragraphs flow. + Usage:: -Command usage -------------- + build-now [] + build-now here [] + build-now [ []] [] -If there aren't many options or examples to show, they can go in a paragraph of -text. Use double-backticks to put commands in monospaced font, like this:: + Where the optional ```` pair can be used to specify the coordinate bounds + within which ``build-now`` will operate. If they are not specified, + ``build-now`` will scan the entire map. If only one ```` is specified, only + the building at that coordinate is built. - You can use ``cleanowned scattered x`` to dump tattered or abandoned items. + The ```` parameters can either be an ``,,`` triple (e.g. + ``35,12,150``) or the string ``here``, which means the position of the active + game cursor. -If the command takes more than three arguments, format the list as a table -called Usage. The table *only* lists arguments, not full commands. -Input values are specified in angle brackets. Example:: +The second option is to arrange the usage options in a list, with the full command +and arguments in monospaced font. Then indent the next line and describe the effect:: Usage: - :arg1: A simple argument. - :arg2 : Does something based on the input value. - :Very long argument: - Is very specific. + ``build-now []`` + Scan the entire map and build all unsuspended constructions and buildings. + ``build-now here []`` + Build the unsuspended construction or building under the cursor. + ``build-now [ []] []`` + Build all unsuspended constructions within the specified coordinate box. -To demonstrate usage - useful mainly when the syntax is complicated, list the -full command with arguments in monospaced font, then indent the next line and -describe the effect:: + The ```` parameters are specified as... - ``resume all`` - Resumes all suspended constructions. +Note that in both options, the entire commandline syntax is written, including the command itself. +Literal text is written as-is (e.g. the word ``here`` in the above example), and text that +describes the kind of parameter that is being passed (e.g. ``pos`` or ``options``) is enclosed in +angle brackets (``<`` and ``>``). Optional elements are enclosed in square brackets (``[`` and ``]``). -Links ------ +Examples +-------- -If it would be helpful to mention another DFHack command, don't just type the -name - add a hyperlink! Specify the link target in backticks, and it will be -replaced with the corresponding title and linked: e.g. ```autolabor``` -=> `autolabor`. Link targets should be equivalent to the command -described (without file extension), and placed above the heading of that -section like this:: +If the only way to run the command is to type the command itself, then this section is not necessary. +Otherwise, please consider adding a section that shows some real, practical usage examples. For +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 +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. - .. _autolabor: +Examples should go in their own subheading with a single dash underline (``--------``). The examples +themselves should be organized in a list, the same as in option 2 for Usage above. Here is an +example Examples section:: - autolabor - ========= + Examples + -------- -Add link targets if you need them, but otherwise plain headings are preferred. -Scripts have link targets created automatically. + ``build-now`` + Completes all unsuspended construction jobs on the map. + ``build-now 37,20,154 here`` + Builds the unsuspended, unconstructed buildings in the box bounded by the coordinate + x=37,y=20,z=154 and the cursor. -Note that the DFHack documentation is configured so that single backticks (with -no prefix or suffix) produce links to internal link targets, such as the -``autolabor`` target shown above. This is different from the reStructuredText -default behavior of rendering such text in italics (as a reference to a title). -For alternative link behaviors, see: +Options +------- -- `The reStructuredText documentation on roles `__ -- `The reStructuredText documentation on external links `__ -- `The Sphinx documentation on roles `__ +The options header should follow the examples, with each option in the same list format as the +examples:: + + Options + ------- + + ``-h``, ``--help`` + Show help text. + ``-l``, ``--quality `` + Set the quality of the architecture for built architected builtings. + ``-q``, ``--quiet`` + Suppress informational output (error messages are still printed). + +Note that for parameters that have both short and long forms, any values that those options +take only need to be specified once (e.g. ````). + +External scripts and plugins +============================ + +Scripts and plugins distributed separately from DFHack's release packages don't have the +opportunity to add their documentation to the rendered HTML or text output. However, these +scripts and plugins can use a different mechanism to at least make their help text available +in-game. + +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. + +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:: + + -- A short description of my cool script. + +and for Ruby scripts it would look like:: + + # A short description of my cool script. + +The main help text for an external script needs to appear between two markers. For +Lua, these markers are ``[====[`` and ``]====]``, and for Ruby they are ``=begin`` and +``=end``. The documentation standards above still apply to external tools, but there is +no need to include backticks for links or monospaced fonts. Here is a Lua example for an +entire script header:: + + -- Inventory management for adventurers. + -- [====[ + gui/adv-inventory + ================= + Tags: adventure, map + + Allows you to quickly move items between containers. This includes yourself + and any followers you have. + + Usage: + + gui/adv-inventory [] + + Examples: + + gui/adv-inventory + Opens the GUI with nothing preselected + gui/adv-inventory take-all + Opens the GUI with all container items already selected and ready to move + into the adventurer's inventory. + + Options: + + take-all + Starts the GUI with container items pre-selected + give-all + Starts the GUI with your own items pre-selected + ]====] - - ``:doc:`` is useful for linking to another document +For external plugins, help text for provided commands can be passed as the ``usage`` +parameter when registering the commands with the ``PluginCommand`` constructor. There +is currently no way for associating help text with the plugin itself, so any +information about what the plugin does when enabled should be combined into the command +help. Required dependencies ===================== @@ -258,8 +404,8 @@ ways to do this: * On Windows, if you prefer to use the batch scripts, you can run ``generate-msvc-gui.bat`` and set ``BUILD_DOCS`` through the GUI. If you are running another file, such as ``generate-msvc-all.bat``, you will need to edit - it to add the flag. You can also run ``cmake`` on the command line, similar to - other platforms. + the batch script to add the flag. You can also run ``cmake`` on the command line, + similar to other platforms. 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