Merge pull request #18 from openSUSE/docs-2

tomschr · web-flow · commit 1c5bcf8a3f46 · 2025-07-05T13:51:30.000+02:00
Improve development and user docs
diff --git a/changelog.d/18.doc.rst b/changelog.d/18.doc.rst
@@ -0,0 +1 @@
+Docs: Improve development and user docs
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -89,6 +89,8 @@
 extlinks = {
     # Example for linking to a specific file/path in the repo:
     'gh_path': (f'{gh_repo_url}/blob/main/%s', '%s'),
+    # Example for linking to a specific directory in the repo:
+    'gh_tree': (f'{gh_repo_url}/tree/main/%s', '%s'),
     # Linking to the GH issue tracker:
     'issue': (f'{gh_repo_url}/issues/%s', 'issue #%s'),
 }
diff --git a/docs/source/developer/build-docs.rst b/docs/source/developer/build-docs.rst
@@ -0,0 +1,18 @@
+.. _build-docs:
+
+Building Documentation
+======================
+
+To build the documentation for this project, use the following steps:
+
+#. Prepare your environment by following the instructions in :ref:`prepare-devel-env`.
+
+#. Build the HTML documentation using the :ref:`makedocs <devel-helpers>` command:
+
+   .. code-block:: shell-session
+      :caption: Building the documentation
+      :name: makedocs
+
+      $ makedocs
+
+#. Find the generated documentation in the :file:`docs/build/html` directory.
diff --git a/docs/source/developer/create-release.rst b/docs/source/developer/create-release.rst
@@ -7,21 +7,21 @@ To create a new release, follow these steps:
 #. Create a new branch for your release. The branch name should follow the format: ``release/<VERSION>``, where ``<VERSION>`` is the version number you are releasing (e.g., ``release/1.0.0``).
 #. Run the alias :command:`bump-version.sh` to update the version number in the project files. For example:
 
-   .. code-block:: shell
+   .. code-block:: shell-session
       :caption: Bump the version number
     
-       bump-version.sh minor
+      $ bump-version.sh minor
 
    This will update the version number to the next minor version (e.g., from `1.0.0` to `1.1.0`).
 #. Update the changelog (see :ref:`update-changelog` for details).
 #. Commit your changes with a message that describes the release.
 #. Wait for the CI to pass. If it fails, fix the issues and commit again.
 #. If the CI passes, (squash-)merge your release branch into the main branch.
-#. Tag the commit in the ``main`` branch with the version number. The release process is triggered by this tag in the format ``MAJOR.MINOR.PATCH``. 
+#. Tag the commit in the ``main`` branch with the version number. The release process is triggered by this tag in the format ``MAJOR.MINOR.PATCH``.
 
    For example, if you are releasing version 1.1.0, you would tag the commit as follows:
 
-   .. code-block:: shell
+   .. code-block:: shell-session
       :caption: Tag the release commit
 
        $ git tag 1.1.0
diff --git a/docs/source/developer/devel-helpers.rst b/docs/source/developer/devel-helpers.rst
@@ -1,7 +1,7 @@
 .. _devel-helpers:
 
-Development helper tools
-------------------------
+Helper Tools
+------------
 
 .. include:: ../../../devel/README.rst
    :start-line: 3
diff --git a/docs/source/developer/index.rst b/docs/source/developer/index.rst
@@ -14,4 +14,7 @@ Developer Guide
    run-ipython
    update-changelog
    create-release
+   trigger-actions
+   knowing-github-setup
+   build-docs
    howto
diff --git a/docs/source/developer/knowing-github-setup.rst b/docs/source/developer/knowing-github-setup.rst
@@ -0,0 +1,32 @@
+.. _know-github-setup:
+
+Knowing GitHub Project Setup
+============================
+
+This project uses GitHub for version control and issue tracking.
+Additionally, it uses GitHub Actions for different tasks like building the documentation, running tests, and creating a release.
+
+
+GitHub Actions
+--------------
+
+* Testing (:file:`.github/workflows/ci.yml`):
+  Runs the test suite on every push and pull request to the main branch.
+  It uses the `pytest` framework to execute tests.
+
+* Documentation (:file:`.github/workflows/gh-pages.yml`):
+  Builds the documentation and deploys it to the `gh-pages` branch.
+  This is triggered on every push to the main branch and on pull requests that target the main. Furthermore it is only triggered if the workflow file itself is changed or anything inside the `docs/` directory.
+  The documentation is available at |gh_repo|.
+
+* Release (:file:`.github/workflows/release.yml`):
+  Create a new release when a tag is pushed to the repository.
+  It is triggered by a tag in the format `MAJOR.MINOR.PATCH`, e.g. `1.0.0`.
+  Currently, it creates a release on GitHub where the description is automatically generated from pull requests and issues that are closed in the release.
+  The releases are available at |gh_release|.
+
+
+Rulesets
+--------
+
+Under https://github.com/openSUSE/docbuild/settings/rules we have rulesets to protect the default branch and tags that matches the semantic versioning format.
diff --git a/docs/source/developer/prepare-environment.rst b/docs/source/developer/prepare-environment.rst
@@ -1,4 +1,4 @@
-.. _prepare-your-devel-environment:
+.. _prepare-devel-env:
 
 Preparing Your Development Environment
 ======================================
@@ -14,10 +14,18 @@ This document provides instructions for setting up a development environment for
    possible to do so.
 
 
-
 .. include:: devel-helpers.rst
 
 
+GitHub CLI
+----------
+
+GiHub CLI is a command-line tool :command:`gh` allows you to interact with GitHub repositories and perform various tasks directly from the terminal.
+
+It is not required for this project, but it can be useful for managing issues, pull requests, and other GitHub-related tasks directly from the terminal.
+
+Find more information at `GitHub CLI <https://cli.github.com/>`_.
+
 
 Starting the development environment
 ------------------------------------
@@ -29,6 +37,8 @@ The following steps are recommended to set up your development environment:
 2. If you haven't created a virtual environment, do so:
 
    .. code-block:: shell-session
+      :caption: Creating a virtual environment with |uv|
+      :name: uv-venv
 
       $ uv venv --prompt venv313 --python 3.13 .venv
 
@@ -37,9 +47,11 @@ The following steps are recommended to set up your development environment:
    The example above uses Python 3.13, but you can adjust it according to your needs as long as it is compatible with the project.
    See file :file:`pyproject.toml` in ``project.requires-python`` for the exact version.
 
-3. Syncronize the virtual environment with the project dependencies, but use the development group instead of the default group:
+3. Synchronize the virtual environment with the project dependencies, but use the development group instead of the default group:
 
    .. code-block:: shell-session
+      :caption: Synchronizing the virtual environment with the development dependencies
+      :name: uv-sync-devel
 
       $ uv sync --frozen --group devel
 
@@ -48,6 +60,8 @@ The following steps are recommended to set up your development environment:
 4. Optionally, source the shell aliases defined in :file:`devel/activate-aliases.sh` to abbreviate the longer :command:`uv` calls (see :ref:`devel-helpers` for more information):
 
    .. code-block:: shell-session
+      :caption: Activating the shell aliases for development
+      :name: activate-aliases
 
       $ source devel/activate-aliases.sh
 
diff --git a/docs/source/developer/trigger-actions.rst b/docs/source/developer/trigger-actions.rst
@@ -0,0 +1,11 @@
+.. _trigger-actions:
+
+Triggering Actions Manually
+===========================
+
+In case you need to trigger a GitHub Action manually, you can do so by using the "Run workflow" button available in the "Actions" tab of the repository on GitHub.
+
+Currently, the following workflows can be triggered manually:
+
+* Testing
+* Documentation
diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
@@ -6,23 +6,39 @@ Glossary
 
    Changelog
       A record of all notable changes made in a project.
+
       See also :ref:`update-changelog`.
 
+   DAPS
+      The *Documentation and Publishing System* (DAPS) is a tool to build documentation from DocBook or ADoc files.
+      It is used to generate various output formats such as HTML, PDF, and EPUB.
+
+   DC File
+      The *DAPS Configuration File* (DC file) is a configuration file used by DAPS to define parameters for building documentation. For example, it contains information about the entry file, what stylesheets to use, and other build options.
+
+   Deliverable
+      The smallest unit of documentation that can be built. It's mapped to a DC File. A deliverable is usually being built in different formats. 
+
    Docset
-      Usually a release or version of a project. For example, 15-SP6.
+      Usually a release or version of a project. For example, ``15-SP6``.
 
    Doctype
       A formal syntax to identify one or many set of documents.
       The syntax is ``[PRODUCT]/[DOCSET][@LIFECYCLES]/LANGS`` and
       contains product, docset, lifecycles, and language.
 
+      See also :ref:`doctype-syntax`.
+
    Lifecycle
       The state of a document in its lifecycle.
-      For example, `supported`, `beta`, `unsupported` or `hidden`.
+      For example, ``supported``, ``beta``, ``unsupported`` or ``hidden``.
+
+      See class :class:`~docbuild.models.lifecycle.LifecycleFlag`.
+
+   Product
+      A abbreviated name for a SUSE product. For example, ``sles``.
 
-   Projects
-      A name for a SUSE project. For example, `sles`.
-      See :class:`~docbuild.models.product.Product`.
+      See class :class:`~docbuild.models.product.Product`.
 
    Virtual Python Environment (VENV)
       A self-contained and isolate directory that contains a Python
diff --git a/docs/source/user/build.rst b/docs/source/user/build.rst
@@ -1,7 +1,9 @@
-Building documentation
-======================
+.. _build-deliverables:
 
-The :command:`docbuild build` subcommand is used to build the documentation from source files. It processes the source files and generates the output in the specified format, such as HTML or PDF.
+Building Deliverables
+=====================
+
+The :command:`docbuild build` subcommand is used to build the deliverables from source files. It processes the source files and generates the output in the specified format, such as HTML or PDF.
 
 .. code-block:: shell
    :caption: Synopsis of :command:`docbuild build`
@@ -17,6 +19,7 @@ describes the document to be built. The general syntax for a doctype is:
 
 .. code-block:: text
    :caption: Doctype syntax
+   :name: doctype-syntax
 
    [PRODUCT]/[DOCSET][@LIFECYCLES]/LANGS
 
diff --git a/docs/source/user/config.rst b/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.
diff --git a/docs/source/user/config/application.rst b/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
diff --git a/docs/source/user/config/environment.rst b/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
diff --git a/docs/source/user/index.rst b/docs/source/user/index.rst
@@ -6,6 +6,7 @@ User Guide
    :caption: Contents
 
    install
+   config
    run-docbuild
    config/index
    build
diff --git a/docs/source/user/install.rst b/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

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Docs: Improve development and user docs`
Original file line number	Diff line number	Diff line change
`@@ -89,6 +89,8 @@`
`89`	`89`	`extlinks = {`
`90`	`90`	`# Example for linking to a specific file/path in the repo:`
`91`	`91`	`'gh_path': (f'{gh_repo_url}/blob/main/%s', '%s'),`
	`92`	`+ # Example for linking to a specific directory in the repo:`
	`93`	`+ 'gh_tree': (f'{gh_repo_url}/tree/main/%s', '%s'),`
`92`	`94`	`# Linking to the GH issue tracker:`
`93`	`95`	`'issue': (f'{gh_repo_url}/issues/%s', 'issue #%s'),`
`94`	`96`	`}`