Improve user documentation

* Amend section "Configuring the Tool" (now in a separate file)
* Small typo fixes

Author: tomschr

changelog.d/18.doc.rst

@@ -1,8 +1 @@
-Docs: Improve development docs
-
-* Try to be consistent with prompts
-* Add some code block captions and names to have a constant anchor
-* Add two new sections:
-  * Triggering Actions Manually
-  * Knowing GitHub Setup
-* Mention GitHub CLI :command:`gh`
+Docs: Improve development and user docs

docs/source/user/config.rst

@@ -0,0 +1,20 @@
+.. _configuring-docbuild:
+
+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.
+
+To use the configuration file, specific it with the option ``--env-config``.
+
+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.
+
+.. code-block:: shell-session
+   :caption: Example aliases for a configuration file
+   :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.

docs/source/user/config/application.rst

@@ -1,4 +1,4 @@
-Showing app's configuration
+Showing App's Configuration
 ===========================
 
 Application configuration files ("app config") affects the behavior of the docbuild tool itself, such as how it processes documents, logging, handles errors, etc.
@@ -18,7 +18,7 @@ If you want to override the default search strategy, use the ``--app-config`` op
    :caption: Showing configuration files
 
    $ docbuild config app
-   # Application config files '/home/tux/repos/GH/tomschr/docbuild/.config.toml'
+   # Application config files '/home/tux/repos/GH/opensuse/docbuild/.config.toml'
    [ ... content ...]
 
 In the previous example, there is a :file:`.config.toml` file in the

docs/source/user/config/environment.rst

@@ -1,4 +1,4 @@
-Showing env's configuration
+Showing Env's Configuration
 ===========================
 
 Environment configuration files ("env config") is specific to the environment in which the docbuild tool operates, such as paths to source files, output directories, and other environment-specific settings.
@@ -11,7 +11,7 @@ If you want to override the default, use the ``--env-config`` option to specify
    :caption: Showing env configuration content
 
    $ docbuild --env-config env.develop.toml config env
-   # ENV Config file '/home/tux/repos/GH/tomschr/docbuild/env.production.toml'
+   # ENV Config file '/home/tux/repos/GH/opensuse/docbuild/env.production.toml'
    [ ... content ...]
 
 In the previous example, there is a :file:`env.production.toml` file in the

docs/source/user/index.rst

@@ -6,6 +6,7 @@ User Guide
    :caption: Contents
 
    install
+   config
    run-docbuild
    config/index
    build

docs/source/user/install.rst

@@ -101,15 +101,7 @@ Installing the tool
 
    .. code-block:: shell-session
 
-      $ uv sync
+      $ uv sync --frozen
       Resolved 29 packages in 586ms
       Built docbuild @ file:///.../docbuild
       Installed 15 packages in 2.11s
-
-
-.. _configuring-docbuild:
-
-Configuring the tool
----------------------
-
-TODO