Add missing doc issues (#178)

* Fix #173: Adjust documentation issues
* Fix a link to the TOML doc
* Fix small typos in docstring or help strings
* Correct title spelling
* Add anchor
* Adjust user doc: config
* Add new "Checking your Environment"

Co-authored-by: Sushant Gaurav <[email protected]>

* Add newsfragment file

---------

Co-authored-by: Sushant Gaurav <[email protected]>

Author: tomschr

changelog.d/173.doc.rst

@@ -0,0 +1,7 @@
+Describe some missing features:
+
+* Document the command :command:`docbuild check files` in the new seciton
+  "Checking your Environment"
+* Add Pydantic definition into glossary
+* Adjusted "Configuring the Tool" section and included placeholders
+  (static & dynamic), key naming conventions, and more.

docs/source/glossary.rst

@@ -141,6 +141,11 @@ For Python specific terms, look into:
 
       See class :class:`~docbuild.models.product.Product`.
 
+   Pydantic
+      A Python library for data validation and settings management using Python type annotations. It provides a way to define data models with strict type checking and validation rules, making it easier to ensure that the data your application works with is correct and consistent.
+
+      See https://pydantic.dev/
+
    :file:`pyproject.toml`
       A configuration file used in Python project to define build system
       requirements and project metadata.

docs/source/reference/_autoapi/docbuild/cli/cmd_config/environment/index.rst

@@ -5,7 +5,7 @@ docbuild.cli.cmd_config.environment
 
 .. autoapi-nested-parse::
 
-   CLI interface to showsthe configuration of the environment files.
+   CLI interface to shows the configuration of the environment files.
 
 
 

docs/source/user/check-env.rst

@@ -0,0 +1,33 @@
+.. _check-environment:
+
+Checking your Environment
+=========================
+
+.. NOTE: This section is work in progress and related to issue #9
+
+
+.. _check-dc-files:
+
+Checking DC Files
+-----------------
+
+From time to time it makes sense to check if the DC files referred in
+the Docbuild XML configuration exist in the repos.
+
+To check all DC files in all repositories, use the following command:
+
+.. code-block:: shell-session
+   :caption: Checking DC files in all repositories
+
+   docbuild --env-config ENV_CONFIG_FILE check dc-files
+
+To check DC files only for a specific product and docset, use the doctype
+syntax:
+
+.. code-block:: shell-session
+   :caption: Checking DC files for SLES 16.0 in English only
+
+   docbuild --env-config ENV_CONFIG_FILE check dc-files 'sles/16.0/en-us'
+
+If a DC file is missing, the tool will report it, allowing you to take
+corrective action.

docs/source/user/config.rst

@@ -5,7 +5,7 @@ Configuring the Tool
 
 .. note::
 
-   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.
+   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.
 
 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.
 
@@ -21,26 +21,144 @@ To use your configuration file, follow these steps one time:
 
 #. 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``.
+#. Specify 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 different configuration files
-   :name: docbuild-aliases
+.. _config-key-naming-conventions:
 
-   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.devel.toml'
+Key Naming Conventions
+----------------------
+
+The keys follow specific naming conventions to indicate their purpose and expected value types. Here are some common patterns whereas the asterisk
+(``*``) represents a variable part of the key:
+
+* ``*_dir``: Contains a directory.
+
+* ``tmp_*``: Indicates a temporary path.
+
+* ``*_dyn``: Denotes a dynamic value that is expected to be resolved at runtime.
+
+Directories are created automatically when the script runs. Additionally,
+the script checks if the specified paths are readable, writeable and belongs
+to the user running the script.
+
+
+.. _config-validation:
+
+Validating the Configuration
+-----------------------------
+
+Before docbuild executes any commands, it validates the provided configuration
+file against a predefined :term:`Pydantic` model.
+
+The validation checks for different aspects of the configuration, such as:
+
+* Presence of mandatory keys.
+* Correct data types (for example, strings, integers, lists).
+* Valid paths and if they exist on the filesystem and are writable when
+  required.
+* Correct use of placeholders.
+
+
+..
+   TODO: Add a link to the TOML env config reference, add an example of
+   a validation error message, and explain how to fix common issues.
+   a validation error message, and explain how to fix common issues.
+
+
+.. _config-placeholders:
+
+Using Placeholders
+------------------
+
+Docbuild supports the use of placeholders in the configuration file.
+Two types of placeholders are supported:
+
+* **Static placeholders** (Syntax ``{placeholder}``)
+
+  They are used to reference *other parts* of the configuration.
+  For example, assume you have a configuration key ``paths.root_config_dir`` that defines the root directory for configuration files. You can use a static placeholder like ``{paths.root_config_dir}`` in other parts of the configuration to refer to this value.
+
+  This allows you to maintain consistency and avoid repeating the same path multiple times in your configuration file.
+
+
+* **Dynamic placeholders** (Syntax ``{{placeholder}}``)
+
+  These types of placeholder cannot and must not be replaced. They are meant to be used as *templates* for values that will be resolved at runtime. For example, you might have a placeholder like ``{{product}}`` that is intended to be replaced with the actual product name when the docbuild tool runs.
+
+  This allows for greater flexibility and adaptability in your configuration, as the same configuration file can be used across different products or environments without needing to hardcode specific values.
+
+These types of placeholder make it easier to manage and maintain your configuration files, as they allow you to centralize key values and create reusable templates for dynamic content.
+
+Static placeholders follow a specific syntax:
+
+* **Regular name** (Syntax ``{placeholder}``)
+
+  A regular name refers to another key in the same section:
+
+  .. code-block:: toml
+     :emphasize-lines: 3
+
+     [paths]
+     root_config_dir = "~/repos/GL/susedoc/docserv-config"
+     jinja_dir = "{root_config_dir}/jinja-doc-suse-com"
+
+  In the previous example, the key ``jinja_dir`` uses a static placeholder
+  ``{root_config_dir}`` to reference the value of the same key
+  ``root_config_dir`` within the same section.
+
+* **Section name** (Syntax ``{section.key}``)
+
+  A section name refers to a key in another section:
+
+  .. code-block:: toml
+     :emphasize-lines: 5
+
+     [server]
+     name = "doc-example-com"
+
+     [paths]
+     base_cache_dir = "/tmp/cache"
+     base_server_cache_dir = "{base_cache_dir}/{server.name}"
+     base_server_cache_dir = "{base_cache_dir}/{server.name}"
+
+  In this example, the key ``base_server_cache_dir`` uses the
+  static placeholder ``{server.name}`` to reference the value of the
+  key ``name`` in the ``server`` section.
+
+  If you have nested sections, use dot notation to reference the keys (for example, ``section.subsection.key``).
+
+
+.. _config-viewing-docbuild-config-env:
 
 Viewing the Environment Configuration
 -------------------------------------
 
-To see how ``docbuild`` interprets your environment configuration, use the ``config env`` subcommand. This is particularly useful for verifying that all placeholders (like ``{{product}}`` or ``{{lang}}``) have been correctly resolved into absolute paths.
+To see how ``docbuild`` interprets your environment configuration, use the
+``config env`` subcommand. This is particularly useful for verifying that all
+static placeholders have been correctly resolved into absolute paths.
 
 .. code-block:: shell-session
    :caption: Displaying the resolved environment configuration
 
-   docbuild config env
+   docbuild --env-config=YOUR_TOML_CONFIG config env
 
 If the configuration contains errors—such as missing mandatory keys or invalid data types—the command will output a validation error detailing what needs to be fixed.
+
+
+.. _config-use-multiple-env-configs:
+
+Using Multiple Environment Configurations
+-----------------------------------------
+
+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 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.devel.toml'

docs/source/user/config/environment.rst

@@ -1,3 +1,5 @@
+.. _config-show-env:
+
 Showing Env's Configuration
 ===========================
 
@@ -20,4 +22,4 @@ current project's directory.
 .. note::
 
    An example of an environment configuration file is provided in this repo
-   in the :gh_path:`etc/docbuild/env.example.toml` directory.
+   in the :gh_path:`etc/docbuild/env.example.toml` directory.

docs/source/user/config/index.rst

@@ -1,11 +1,11 @@
-Showing configuration
+Showing Configuration
 =====================
 
 The docbuild tool distinguishes between two types of configuration files:
 
-* **Application configuration files ("app config")**
+* Application configuration files ("app config")
 
-* **Environment configuration files ("env config")**
+* Environment configuration files ("env config")
 
 Additionally, the docbuild tool has also hardcoded default values for both types of configuration.
 
@@ -17,7 +17,7 @@ Keep in mind that these defaults may not be suitable for all use cases, and it i
 
 .. admonition:: TOML as default format
 
-   Both configuration types are written in TOML format, which is a human-readable data serialization standard. See `TOML docs <https://toml.io/en/>_` for more information on its syntax and structure.
+   Both configuration types are written in TOML format, which is a human-readable data serialization standard. See `TOML docs <https://toml.io/en/>`_ for more information on its syntax and structure.
 
 The following subsections provide more details on how to view and manage the configuration files for both application and environment settings.
 

docs/source/user/index.rst

@@ -13,3 +13,4 @@ User Guide
    validate
    clone
    metadata
+   check-env

src/docbuild/cli/cmd_cli.py

@@ -66,7 +66,7 @@ def _setup_console() -> None:
     help=(
         "Enable debug mode. "
         "This will show more information about the process and the config files. "
-        "If available, read the environment variable 'DOCBUILD_DEBUG'."
+        "If available, read the environment variable ``DOCBUILD_DEBUG``."
     ),
 )
 @click.option(

src/docbuild/cli/cmd_config/environment.py

@@ -1,4 +1,4 @@
-"""CLI interface to showsthe configuration of the environment files."""
+"""CLI interface to shows the configuration of the environment files."""
 
 import click
 from rich import print_json