Merge pull request #5569 from lethosor/docs-docs-improvements

Documentation system docs improvements

Author: ab9rf

CMakeLists.txt

@@ -523,7 +523,7 @@ if(BUILD_DOCS)
 
     add_custom_command(OUTPUT ${SPHINX_OUTPUT}
         COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/docs/build.py"
-        ${SPHINX_BUILD_TARGETS} --sphinx="${SPHINX_EXECUTABLE}" -- -q -W
+        ${SPHINX_BUILD_TARGETS} --sphinx="${SPHINX_EXECUTABLE}" --quiet -- -W
         DEPENDS ${SPHINX_DEPS}
         COMMENT "Building documentation with Sphinx"
     )

docs/build.py

@@ -62,6 +62,8 @@ def output_format(s):
         help='Sphinx executable to run [environment variable: SPHINX; default: "sphinx-build"]')
     parser.add_argument('-j', '--jobs', type=str, default=os.environ.get('JOBS', 'auto'),
         help='Number of Sphinx threads to run [environment variable: JOBS; default: "auto"]')
+    parser.add_argument('-q', '--quiet', action='store_true',
+        help='Disable most output on stdout (also passed to sphinx-build)')
     parser.add_argument('--debug', action='store_true',
         help='Log commands that are run, etc.')
     parser.add_argument('--offline', action='store_true',
@@ -91,11 +93,14 @@ def output_format(s):
         command = [args.sphinx] + OUTPUT_FORMATS[format_name].args + ['-j', args.jobs]
         if args.clean:
             command += ['-E']
+        if args.quiet:
+            command += ['-q']
         command += forward_args
 
         if args.debug:
             print('Building:', format_name)
             print('Running:', command)
         subprocess.run(command, check=True, env=sphinx_env)
 
-        print('')
+        if not args.quiet:
+            print('')

docs/changelog.txt

@@ -1,26 +1,30 @@
 === Scroll down for changes
 
 ===[[[
-The text below is included in docs/dev/Documentation.rst - see that file for more details on the changelog setup.
-This is kept in this file as a quick syntax reference.
+For information on how to edit/build the changelogs, see `docs/html/docs/dev/Documentation.html` or `docs/dev/Documentation.rst`.
 
-===help
+The text between the `syntax-reference` markers is included in `docs/dev/Documentation.rst`, so it must be valid RST.
+It is kept in this file as a quick syntax reference.
 
-changelog.txt uses a syntax similar to RST, with a few special sequences:
+===syntax-reference-start
+
+The changelogs use a syntax similar to RST, with a few special sequences:
 
 - ``===`` indicates the start of a comment
 - ``#`` indicates the start of a release name (do not include "DFHack")
-- ``##`` indicates the start of a section name (this must be listed in ``gen_changelog.py``)
+- ``##`` indicates the start of a section name (which must be listed in ``docs/sphinx_extensions/dfhack/changelog.py``)
 - ``-`` indicates the start of a changelog entry. **Note:** an entry currently must be only one line.
-- ``:`` (colon followed by space) separates the name of a feature from a description of a change to that feature.
-    Changes made to the same feature are grouped if they end up in the same section.
-- ``:\`` (colon, backslash, space) avoids the above behavior
-- ``- @`` (the space is optional) indicates the start of an entry that should only be displayed in NEWS-dev.rst.
-    Use this sparingly, e.g. for immediate fixes to one development build in another development build that
-    are not of interest to users of stable builds only.
+- ``:`` (followed by space) separates the name of a feature from a description of a change to that feature.
+    - Changes made to the same feature are grouped if they end up in the same section.
+- ``:\`` (followed by space) avoids the above behavior
+- ``- @`` (the space is optional) indicates the start of an entry that should only be displayed in ``NEWS-dev.rst``.
+    - Use this sparingly, e.g. for immediate fixes to one development build in another development build that
+      are not of interest to users of stable builds only.
 - Three ``[`` characters indicate the start of a block (possibly a comment) that
   spans multiple lines. Three ``]`` characters indicate the end of such a block.
-- ``!`` immediately before a phrase set up to be replaced (see gen_changelog.py) stops that occurrence from being replaced.
+- ``!`` immediately before a configured replacement (see ``docs/sphinx_extensions/dfhack/changelog.py``) stops that occurrence from being replaced.
+
+===syntax-reference-end
 
 Template for new versions:
 
@@ -40,7 +44,6 @@ Template for new versions:
 
 ## Removed
 
-===end
 ]]]
 
 ================================================================================

docs/dev/Documentation.rst

@@ -67,6 +67,8 @@ with relevant tags. These are used to compile indices and generate cross-links b
 commands, both in the HTML documents and in-game. See the list of available `tag-list` and
 think about which categories your new tool belongs in.
 
+.. _docs-links:
+
 Links
 -----
 
@@ -418,6 +420,8 @@ Once you have pip available, you can install Sphinx with the following command::
 Note that this may require opening a new (admin) command prompt if you just
 installed pip from the same command prompt.
 
+.. _docs-build:
+
 Building the documentation
 ==========================
 
@@ -427,16 +431,18 @@ Sphinx to build the docs:
 Using CMake
 -----------
 
-See our page on `build options <building-documentation>`
+See our page on `build options <building-documentation>`.
 
-Running Sphinx manually
------------------------
+Using the documentation build script
+------------------------------------
 
 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
-``docs/build.py`` script will build the documentation in any specified formats
-(HTML only by default) using the same command that CMake runs when building the
-docs. Run the script with ``--help`` to see additional options.
+you only want to rebuild the documentation regardless of any code changes.
+
+The recommended approach is the ``docs/build.py`` script. This is the same
+script that CMake uses internally, which wraps Sphinx with a few additional
+options to handle common cases and can build multiple documentation formats with
+a single invocation.
 
 Examples:
 
@@ -449,15 +455,43 @@ Examples:
 * ``docs/build.py --clean``
     Build HTML and force a clean build (all source files are re-read)
 
-The resulting documentation will be stored in ``docs/html`` and/or ``docs/text``.
+* ``docs/build.py --help``
+    Display a full list of available options
+
+The resulting documentation will be stored in ``docs/html`` and/or ``docs/text``
+(or generally, a subfolder of ``docs/`` named after the requested output format(s)).
+
+Building a PDF version
+----------------------
+
+ReadTheDocs automatically builds a PDF version of the documentation (available
+under the "Downloads" section when clicking on the release selector). If you
+want to build a PDF version locally, you will need the ``pdflatex`` command, which is part
+of a TeX distribution. The following command will then build a PDF, located in
+``docs/pdf/latex/DFHack.pdf``, with default options::
+
+  docs/build.py pdf
+
+Running Sphinx manually
+-----------------------
+
+If ``docs/build.py`` does not support what you need, you can also run Sphinx
+manually. This is primarily useful for low-level debugging.
 
-Alternatively, you can run Sphinx manually with::
+For a good starting point, add the ``--debug`` argument to your call to
+``docs/build.py``. This will cause the script to print out the Sphinx command(s)
+that it is running.
 
-    sphinx-build . docs/html
+Some examples:
 
-or, to build plain-text output::
+* ``sphinx-build . docs/html``
+    Build the HTML docs (equivalent to ``docs/build.py``)
 
-    sphinx-build -b text . docs/text
+* ``sphinx-build -b text . docs/text``
+    Build the plain text docs (equivalent to ``docs/build.py text``)
+
+* ``sphinx-build -M latexpdf . docs/pdf``
+    Build the PDF docs
 
 Sphinx has many options to enable clean builds, parallel builds, logging, and
 more - run ``sphinx-build --help`` for details. If you specify a different
@@ -466,20 +500,47 @@ 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
-----------------------
+Troubleshooting
+===============
 
-ReadTheDocs automatically builds a PDF version of the documentation (available
-under the "Downloads" section when clicking on the release selector). If you
-want to build a PDF version locally, you will need ``pdflatex``, which is part
-of a TeX distribution. The following command will then build a PDF, located in
-``docs/pdf/latex/DFHack.pdf``, with default options::
+Sphinx errors are typically printed by Sphinx, so ensure that you are not silencing Sphinx output.
 
-  docs/build.py pdf
+When built with ``docs/build.py`` or CMake, errors are also logged to
+``build/docs/<format>/sphinx-warnings.txt`` (for instance, if you are building
+the HTML docs, ``build/docs/html/sphinx-warnings.txt``).
+
+
+"undefined label"
+-----------------
+
+Typical causes:
+
+* You have used single backticks for an inline code snippet, where double backticks should be used instead (see `docs-links`)::
+
+    `this is an invalid inline code snippet (actually a link)`
+    ``this is a valid inline code snippet``
+
+* You are attempting to link to a section/label, but either it does not have a label defined or you have spelled it incorrectly::
+
+    .. my-label:
+
+    This is where the link should go to.
+
+    ...
+
+    This is `a valid link to the earlier label <my-label>`. So is `my-label`.
+
+"toctree contains reference to document that doesn't have a title"
+------------------------------------------------------------------
+
+Due to the nature of our autogenerated documentation, this can sometimes occur
+when switching between branches that have different autogenerated files, and can
+result in autogenerated documentation (e.g. for individual tools) being missing
+from the table of contents, or links failing to generate.
 
-Alternatively, you can run Sphinx manually with::
+The quickest resolution is a clean docs build::
 
-  sphinx-build -M latexpdf . docs/pdf
+    docs/build.py --clean
 
 .. _build-changelog:
 
@@ -515,8 +576,8 @@ Changelog syntax
 ----------------
 
 .. include:: /docs/changelog.txt
-   :start-after: ===help
-   :end-before: ===end
+   :start-after: ===syntax-reference-start
+   :end-before: ===syntax-reference-end
 
 .. _docs-ci:
 

docs/dev/compile/Options.rst

@@ -136,16 +136,26 @@ Usage::
 
 Documentation
 =============
-If you need to build documentation. Documentation can be built as HTML, and PDF,
-but there are also plain text files generated for in-game.
+If you need to build `documentation <documentation>`.
 
-Variable: ``BUILD_DOCS``
+.. note::
+
+    These options are primarily useful for verifying that the end-to-end process
+    for building and packaging the documentation is working as expected. For
+    iterating on documentation changes, `faster alternatives <docs-build>` are
+    available.
+
+Variables:
+
+* ``BUILD_DOCS``: enables the default documentation build
+* ``BUILD_DOCS_NO_HTML``: disables the HTML documentation build (only builds the text documentation used in-game)
 
 Usage::
 
     cmake .. -DBUILD_DOCS:bool=ON
     cmake .. -DBUILD_DOCS=1
-
+    cmake .. -DBUILD_DOCS_NO_HTML:bool=ON
+    cmake .. -DBUILD_DOCS_NO_HTML=1
 
 The generated documentation is stored in ``docs/html`` and ``docs/text`` (respectively)
 in the root DFHack folder, and they will both be installed to ``hack/docs`` when you