Improve user documentation (#47)

* Move "XML configuration" section to user guide
  Also change title, set an anchor, and make it clear why we need that.
* Create a new glossary entry TOML
* Revise "Configuring the Tool"
* Add URLs to Sphinx extensions
* Amend IDEAS
* Raise maxdepth for main index

Author: tomschr

IDEAS.md

@@ -16,9 +16,24 @@ This is a unsorted collection of ideas what could be implemented.
 
 * Implement a "check environment" function.
   Before we really do anything, this check some prerequisites:
-   * Checks if certain commands are available (e.g. `git`, `jing`)
-   * Check if commands have a minimum version
-   * Check if the available space is enough (can be customized in the envconfig)
-   * More...?
+  * Checks if certain commands are available (e.g. `git`, `jing`)
+  * Check if commands have a minimum version
+  * Check if the available space is enough (can be customized in the envconfig)
+  * More...?
 
   This should help that it breaks in the middle of, for example, a build operation.
+
+* An async `anext()` function (resembles the original `next()` function both
+  in terms of interface and behavior):
+
+    ```python
+    NOT_SET = object()
+
+    async def anext(async_generator_expression, default=NOT_SET):
+        try:
+            return await async_generator_expression.__anext__()
+        except StopAsyncIteration:
+            if default is NOT_SET:
+                raise
+            return default
+    ```

changelog.d/47.doc.rst

@@ -0,0 +1,2 @@
+Improve user documentation.
+Move "XML configuration" section to user guide. Also change title, set an anchor, and make it clear why we need that. Revise "Configuring the Tool" section.

docs/source/conf.py

@@ -38,23 +38,40 @@
 
 extensions = [
     # Include documentation from docstrings
+    # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
     'sphinx.ext.autodoc',
+    #
     # Link to other projects' documentation
+    # https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
     'sphinx.ext.intersphinx',
+    #
     # Test code snippets in the documentation
+    # https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html
     'sphinx.ext.doctest',
+    #
     # Create short aliases for external links
+    # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
     'sphinx.ext.extlinks',
+    #
+    # Embed Graphviz graphs
+    # https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html
+    'sphinx.ext.graphviz',
+    #
     # Document Click command-line interfaces
+    # https://sphinx-click.readthedocs.io/en/latest/
     'sphinx_click',
+    #
     # Add a "copy" button to code blocks
+    # https://sphinx-copybutton.readthedocs.io/en/latest/
     'sphinx_copybutton',
+    #
     # Render type hints in signatures
+    # https://github.com/tox-dev/sphinx-autodoc-typehints
     'sphinx_autodoc_typehints',
+    #
     # Generate API documentation from source code
+    # https://sphinx-autoapi.readthedocs.io/en/latest/
     'autoapi.extension',
-    # Embed Graphviz graphs
-    'sphinx.ext.graphviz',
 ]
 
 templates_path = ['_templates']

docs/source/developer/project-dependencies.rst

@@ -58,12 +58,3 @@ External tools
 * :command:`make` is used to build the documentation.
 * :command:`jing`: for validation the XML configuration files.
 * :command:`gh`: optional tool for interacting with GitHub, see :ref:`github-cli`.
-
-
-
-XML configuration
------------------
-
-Formerly known as the *Docserv XML configs*. These configuration files defines the :term:`products <Product>`, their :term:`releases <Docset>`, their :term:`lifecycle <Lifecycle>` status and more.
-
-Clone the |gl_xmlconfig| or use the RNC schema from :gh_tree:`src/docbuild/config/xml/data/` to create this configuration.

docs/source/glossary.rst

@@ -132,7 +132,7 @@ For Python specific terms, look into:
       A configuration file used in Python project to define build system
       requirements and project metadata.
 
-      See :pep:`518`
+      See :pep:`518`, :term:`TOML`
 
    Pytest
       A testing framework. It's used to write, organize, and run
@@ -166,6 +166,12 @@ For Python specific terms, look into:
 
       See section :ref:`build-docs`.
 
+   TOML
+      *Tom's Obvious, Minimal Language* is a configuration file format
+      used to define environment settings for the docbuild tool.
+
+      See https://toml.io/en/
+
    UV
       A fast package manager which simplifies the building, installing,
       and managing of this project.

docs/source/index.rst

@@ -11,7 +11,7 @@ This is the documentation for the |project| project, hosted at |gh_repo|.
 
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :caption: Contents
 
    user/index

docs/source/user/config.rst

@@ -3,18 +3,32 @@
 Configuring the Tool
 ---------------------
 
-Currently, the environment configuration is done via a TOML file. An example configuration file is provided in the repository. find it at :gh_tree:`etc/docbuild/env.example.toml`. Copy it to your working directory and name it accordingly to your purpose, for example, ``env.development.toml``, ``env.testing.toml``, or ``env.production.toml``. Modify it according to your needs.
+.. note::
 
-To use the configuration file, specific it with the option ``--env-config``.
+   To prevent accidental commits of sensitive information, all configuration files matching the :file:`env.*.toml` pattern in the root directory are ignored by git. However, this rule does not apply to files within the :file:`etc/` directory.
 
-If you need to deal with different environments (testing, staging, production), it can be tedious to type. In such a case, use aliases in your shell.
+Use separate TOML files to define the configuration for each of your environments. To avoid confusion, name each file according to its specific purpose. For instance, use :file:`env.devel.toml` for development, :file:`env.staging.toml` for staging, and :file:`env.production.toml` for production.
+
+An example configuration file is provided in the repository at :gh_tree:`etc/docbuild/env.example.toml`.
+
+To use your configuration file, follow these steps one time:
+
+#. In your cloned GitHub repository, copy the example file :file:`etc/docbuild/env.example.toml` to the root directory of this project. For example::
+
+     cp etc/docbuild/env.example.toml env.devel.toml
+
+#. Open your TOML file.
+
+#. Adjust the path ``paths.root_config_dir``. Use the path from :ref:`get-xml-config`. The rest can stay as it is.
+
+#. Specific the configuration with the global option ``--env-config``.
+
+To deal with different environments without having to type the full command each time, create aliases in your shell. This allows you to quickly switch between configurations without needing to remember the exact command syntax.
 
 .. code-block:: shell-session
-   :caption: Example aliases for a configuration file
+   :caption: Example aliases for different configuration files
    :name: docbuild-aliases
 
    $ alias docbuild-prod='docbuild --env-config env.production.toml'
    $ alias docbuild-test='docbuild --env-config env.testing.toml'
-   $ alias docbuild-dev='docbuild --env-config env.development.toml'
-
-Keep in mind, all configuration files that match the pattern ``env.*.toml`` are ignored by git. This is on purpose to prevent accidental commits of sensitive information.
+   $ alias docbuild-dev='docbuild --env-config env.devel.toml'

docs/source/user/install.rst

@@ -3,11 +3,13 @@ Installing docbuild
 
 To install the docbuild tool, follow these steps:
 
-1. :ref:`prepare-installation` - Prepare your environment for installation.
+#. :ref:`prepare-installation` - Prepare your environment for installation.
 
-2. :ref:`installing-docbuild` - Install the docbuild tool itself.
+#. :ref:`installing-docbuild` - Install the docbuild tool itself.
 
-3. :ref:`configuring-docbuild` - Configure the docbuild tool to suit your needs.
+#. :ref:`get-xml-config` - Get the XML configuration files required for building documentation.
+
+#. :ref:`configuring-docbuild` - Configure the docbuild tool to suit your needs.
 
 
 .. _prepare-installation:
@@ -45,15 +47,15 @@ There are different methods to install the :command:`uv` package manager
 
    You should see the version of :command:`uv` printed in the terminal.
 
-3. **Install Python 3.13 or higher**
+3. **Install Python 3.12 or higher**
 
    As of the time of writing, the docbuild tool requires Python 3.12 or higher. Install the Python version using :command:`uv`:
 
    .. code-block:: shell-session
 
       $ uv python install 3.13
 
-   This command will download Python 3.13 and install it in the directory :file:`~/.local/share/uv/python/<VERSION>`.
+   The previous command downloads Python 3.13 and install it in the directory :file:`~/.local/share/uv/python/<VERSION>`.
 
 4. **Check the available Python versions**
 
@@ -105,3 +107,16 @@ Installing the tool
       Resolved 29 packages in 586ms
       Built docbuild @ file:///.../docbuild
       Installed 15 packages in 2.11s
+
+
+.. _get-xml-config:
+
+Getting the XML configuration
+-----------------------------
+
+Formerly known as the *Docserv XML configs*. These configuration files defines the :term:`products <Product>`, their :term:`releases <Docset>`, their :term:`lifecycle <Lifecycle>` status and more.
+
+The tool needs the XML configuration to build the documentation correctly. The XML configuration is not part of the docbuild tool itself, but it is required to run the tool.
+
+Clone the |gl_xmlconfig| to your machine where you can access it easily.
+As an alternative, use the RNC schema from :gh_tree:`src/docbuild/config/xml/data/` to create your own configuration.