From b122870b6a0e5b43d962c6c9be810139e0a9aa60 Mon Sep 17 00:00:00 2001 From: lethosor Date: Tue, 7 Jul 2020 01:54:59 -0400 Subject: [PATCH] Move documentation standards to Documentation.rst --- Contributing.rst | 89 +------------------------------ docs/Documentation.rst | 115 ++++++++++++++++++++++++++++++++++++----- 2 files changed, 104 insertions(+), 100 deletions(-) diff --git a/Contributing.rst b/Contributing.rst index e358e66b3..cb9e87a0e 100644 --- a/Contributing.rst +++ b/Contributing.rst @@ -32,6 +32,7 @@ How to get new code into DFHack (i.e. not the master or develop branch of your fork). * If possible, compile on multiple platforms when changing anything that compiles * It must pass CI - run ``python travis/all.py`` to check this. +* Update documentation when applicable - see `docs-standards` for details. * Update ``changelog.txt`` and ``docs/Authors.rst`` when applicable. See `build-changelog` for more information on the changelog format. * Create a GitHub pull request once finished @@ -126,94 +127,6 @@ know what exactly is most useful. `remotefortressreader` provides a fairly comprehensive interface for visualisers such as :forums:`Armok Vision <146473>`. -Documentation Standards -======================= -DFHack documentation is built with Sphinx_, and configured automatically -through CMake. If you want to build the docs *only*, use this command:: - - sphinx-build . docs/html - -Whether you're adding new code or just fixing old documentation (and there's plenty), -there are a few important standards for completeness and consistent style. Treat -this section as a guide rather than iron law, match the surrounding text, and you'll -be fine. - -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! - -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! - -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 (eg.) printing it when a ``-help`` argument -is given. - -The docs **must** have a heading which exactly matches the command, underlined -with ``=====`` to the same length. For example, a lua file would have:: - - local helpstr = [====[ - - 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. - - ]====] - - -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. - -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. - -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:: - - You can use ``cleanowned scattered x`` to dump tattered or abandoned items. - -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:: - - Usage: - - :arg1: A simple argument. - :arg2 : Does something based on the input value. - :Very long argument: - Is very specific. - -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:: - - ``resume all`` - Resumes all suspended constructions. - -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: eg ```autolabor``` -=> `autolabor`. Link targets should be equivalent to the command -described (without file extension), and placed above the heading of that -section like this:: - - .. _autolabor: - - autolabor - ========= - -Add link targets if you need them, but otherwise plain headings are preferred. -Scripts have link targets created automatically. - Other ways to help ================== DFHack is a software project, but there's a lot more to it than programming. diff --git a/docs/Documentation.rst b/docs/Documentation.rst index f7cb9ef92..2fa32e16c 100644 --- a/docs/Documentation.rst +++ b/docs/Documentation.rst @@ -28,21 +28,118 @@ The main thing you lose in plain text format is hyperlinking.) .. contents:: +.. _docs-standards: + +Documentation standards +======================= + +Whether you're adding new code or just fixing old documentation (and there's plenty), +there are a few important standards for completeness and consistent style. Treat +this section as a guide rather than iron law, match the surrounding text, and you'll +be fine. + +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! + +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! + +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 (eg.) printing it when a ``-help`` argument +is given. + +The docs **must** have a heading which exactly matches the command, underlined +with ``=====`` to the same length. For example, a lua file would have:: + + local helpstr = [====[ + + 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. + + ]====] + + +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. + +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. + +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:: + + You can use ``cleanowned scattered x`` to dump tattered or abandoned items. + +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:: + + Usage: + + :arg1: A simple argument. + :arg2 : Does something based on the input value. + :Very long argument: + Is very specific. + +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:: + + ``resume all`` + Resumes all suspended constructions. + +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: eg ```autolabor``` +=> `autolabor`. Link targets should be equivalent to the command +described (without file extension), and placed above the heading of that +section like this:: + + .. _autolabor: + + autolabor + ========= + +Add link targets if you need them, but otherwise plain headings are preferred. +Scripts have link targets created automatically. + + +Building the documentation +========================== + Required dependencies -===================== +--------------------- In order to build the documentation, you must have Python with Sphinx -version 1.3.1 or later. Both Python 2.x and 3.x are supported. +version 1.8 or later. Both Python 2.x and 3.x are supported. When installing Sphinx from OS package managers, be aware that there is another program called Sphinx, completely unrelated to documentation management. 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. +Once you have installed Sphinx, ``sphinx-build --version`` should report the +version of Sphinx that you have installed. If this works, CMake should also be +able to find Sphinx. + For more detailed platform-specific instructions, see the sections below: +.. contents:: + :local: + Linux ------ +~~~~~ Most Linux distributions will include Python as standard. Check your package manager to see if Sphinx 1.3.1 or later is available, @@ -66,7 +163,7 @@ install, find ``sphinx-build`` and ensure its directory is in your local ``$PATH macOS ------ +~~~~~ macOS has Python 2.7 installed by default, but it does not have the pip package manager. You can install Homebrew's Python 3, which includes pip, and then install the @@ -87,7 +184,7 @@ If not, just installing sphinx-doc for macOS's system Python 2.7 is fine. Windows -------- +~~~~~~~ Python for Windows can be downloaded `from python.org `_. The latest version of Python 3 is recommended, as it includes pip already. @@ -105,13 +202,6 @@ Note that this may require opening a new (admin) command prompt if you just installed pip from the same command prompt. -Building the documentation -========================== - -Once you have installed Sphinx, ``sphinx-build --version`` should report the -version of Sphinx that you have installed. If this works, CMake should also be -able to find Sphinx. - Using CMake ----------- @@ -155,6 +245,7 @@ the root DFHack folder:: Sphinx has many options to enable clean builds, parallel builds, logging, and more - run ``sphinx-build --help`` for details. + .. _build-changelog: Building the changelogs