Add project dependencies (#40)

tomschr · web-flow · commit 450c5889b854 · 2025-07-11T20:46:51.000+02:00
* Describe project and system dependencies
* Add link to susedoc/docserv-config
* Amend glossary
diff --git a/changelog.d/40.doc.rst b/changelog.d/40.doc.rst
@@ -0,0 +1 @@
+Add project dependencies, add link to ``susedoc/docserv-config`` repo, and amend the glossary
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -17,16 +17,20 @@
 gh_repo_url = f'https://github.com/{gh_user}/{project}'
 gh_repo_slug = f'{gh_user}/{project}'
 
+xml_config_repo = 'https://gitlab.suse.de/susedoc/docserv-config'
+xml_config_slug = '/'.join(xml_config_repo.rsplit('/', 2)[-2:])
 
 # --- Prolog configuration
 rst_prolog = f"""
+.. |daps| replace:: :command:`daps`
 .. |project| replace:: {project}
 .. |gh_repo_slug| replace:: {gh_repo_slug}
 .. |github_user| replace:: {gh_user}
 .. |gh_repo| replace:: {gh_repo_url}
 .. |gh_repo_url| replace:: `{gh_repo_slug} <{gh_repo_url}>`__
 .. |uv| replace:: :command:`uv`
 .. |gh_release| replace:: `Releases <{gh_repo_url}/releases/>`__
+.. |gl_xmlconfig| replace:: `GL://{xml_config_slug} <{xml_config_repo}>`__
 """
 
 # -- General configuration
@@ -144,7 +148,7 @@
     'icon_links': [
         {
             'name': 'GitLab susedoc/docserv-config',
-            'url': 'https://gitlab.suse.de/susedoc/docserv-config',
+            'url': xml_config_repo,
             'icon': 'fa-brands fa-square-gitlab',
             'type': 'fontawesome',
         },
diff --git a/docs/source/developer/index.rst b/docs/source/developer/index.rst
@@ -14,6 +14,7 @@ This guide provides all the necessary information for contributing to the projec
    :maxdepth: 2
    :caption: Tasks
 
+   project-dependencies
    prepare-environment
    develop-project
    run-testsuite
diff --git a/docs/source/developer/prepare-environment.rst b/docs/source/developer/prepare-environment.rst
@@ -46,6 +46,9 @@ The following diagram illustrates the relationship between the main components o
 .. include:: devel-helpers.rst
    :start-after: -text-begin-
 
+
+.. _github-cli:
+
 GitHub CLI
 ----------
 
@@ -61,9 +64,9 @@ Setting up the development environment
 
 The following steps are recommended to set up your development environment:
 
-1. Follow the steps in :ref:`prepare-installation` and :ref:`installing-docbuild`.
+#. Follow the steps in :ref:`prepare-installation` and :ref:`installing-docbuild`.
 
-2. If you haven't created a virtual environment, do so:
+#. If you haven't created a virtual environment, do so:
 
    .. code-block:: shell-session
       :caption: Creating a virtual environment with |uv|
@@ -76,7 +79,7 @@ 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. Synchronize the virtual environment with the project dependencies, but use the development group instead of the default group:
+#. 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
@@ -86,7 +89,7 @@ The following steps are recommended to set up your development environment:
 
    The option ``--frozen`` ensures that the dependencies are installed exactly as specified in the lock file, preventing any unexpected changes.
 
-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):
+#. 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
diff --git a/docs/source/developer/project-dependencies.rst b/docs/source/developer/project-dependencies.rst
@@ -0,0 +1,69 @@
+.. _project-deps:
+
+Project Dependencies
+====================
+
+Although this project contains pure Python code, it needs other dependencies to work correctly:
+
+* **Python installation dependencies**
+
+  Minimum dependencies that the program can run at all.
+
+* **Testing dependencies**
+
+  Dependencies used for testing.
+
+* **Documentation Dependencies**
+
+  For building the documentation.
+
+* **System dependencies**
+
+  These are explained in this topic.
+
+All of the above points (except for the last one) are defined in the :file:`pyproject.toml` file.
+
+
+Operating System
+----------------
+
+The code is developed on openSUSE, but should work on any Linux distribution.
+The project will support MacOS too. It's currently not planned to support Windows.
+
+
+.. note::
+
+    If you use a different OS than Linux, dependency resolution may be challenging. Either the required package is not available for your OS or it is hard to get it right.
+
+    You may have a better experience developing in a virtual machine running openSUSE or using a Docker container.
+
+
+Python
+------
+
+The minimal Python version is defined in the :file:`pyproject.toml` file. It's strongly recommended to have the Python versions managed by |uv|.
+
+
+Editor
+------
+
+You can use any editor you like. Rudimentary support is available for `VSCode <https://code.visualstudio.com/>`_.
+
+
+External tools
+--------------
+
+* |daps|: our tool to build documentation. This is an obligatory requirement. This adds other dependencies.
+* |uv|, the Python package manager. This is explained in :ref:`devel-helpers`.
+* :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.
diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
@@ -4,11 +4,37 @@ Glossary
 .. glossary::
    :sorted:
 
+   ADoc
+   ASCIIDoc
+      A lightweight markup language, similar to Markdown, but with a more powerful and extensive syntax designed for writing complex technical documentation, articles, and books.
+
+      See also :term:`DocBook`, https://docs.asciidoctor.org/asciidoc/latest/.
+
+   Argument
+      * Python: A value or object that you pass into a function/method.
+      * Command-line: Data that the command operates on, usually a file name, a directory path, a URL, or a string of text that the program needs to perform its primary function.
+
+      See also :term:`Option`.
+
+   Asynchronous Programming
+      A style of concurrent programming that allows a program to start long-waiting operations (like a network request) and then perform other work while waiting for the original operation to complete.
+      With the ``async`` and ``await`` keywords, this method prevents the application from blocking on slow I/O tasks, keeping it efficient and responsive.
+
+   asyncio
+      Python's standard library for writing concurrent code using the ``async``/``await`` syntax.
+
+      See also :term:`Asynchronous Programming`
+
    Changelog
       A record of all notable changes made in a project.
 
       See also :ref:`create-release`.
 
+   Concurrency
+      The ability of a system to manage and make progress on multiple tasks over an overlapping time period. It's about dealing with many things at once, but not necessarily executing them at the exact same instant. A single CPU core can be concurrent by rapidly switching between tasks.
+
+      See also :term:`Asynchronous Programming`, :term:`asyncio`, :term:`Parallelism`
+
    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.
@@ -25,7 +51,7 @@ Glossary
       A semantic markup language based on :term:`XML` used for writing
       and publishing technical documentation.
 
-      See https://www.docbook.org
+      See also :term:`ADoc`, https://www.docbook.org
 
    Docset
       Usually a release or version of a project. For example, ``15-SP6``.
@@ -35,21 +61,54 @@ Glossary
       The syntax is ``[PRODUCT]/[DOCSET][@LIFECYCLES]/LANGS`` and
       contains product, docset, lifecycles, and language.
 
-      See also :ref:`doctype-syntax`.
+      See section :ref:`doctype-syntax`.
+
+   GIL
+   Global Interpreter Lock
+      A mutex (a lock) in the standard CPython interpreter that ensures only one thread can execute Python bytecode at any given time within a single process. This lock effectively prevents multi-threaded, CPU-bound Python programs from achieving true parallelism on multi-core processors, as only one thread can run on one core at a time.
+
+      See also :term:`Mutex`.
 
    IPython
       An interactive command-line interface for Python that enhances
       the standard Python shell with additional features.
 
-      See :ref:`use-ipython`.
+      See section :ref:`use-ipython`.
 
    Lifecycle
       Describes the distinct stages a product goes through, from its initial introduction to the market until its eventual decline and retirement.
 
-      This project defines the lifecycle stages ``supported``, ``beta``, ``unsupported`` and ``hidden``.
-
       See class :class:`~docbuild.models.lifecycle.LifecycleFlag`.
 
+   Module
+      In Python context, a single Python file containing code.
+
+      See also :term:`Package`.
+
+   Mutex
+      Short for *Mutual Exclusion*  is a locking mechanism in concurrent programming that ensures only one thread can access a shared resource at any given time. By requiring a thread to "acquire" the lock before using the resource and "release" it afterward, it prevents race conditions and protects shared data from being corrupted.
+
+      See also :term:`Concurrency`.
+
+   Option
+      * Python: An optional settings that modify the function's behavior.
+      * Command-line: a flag or switch that modifies a program's execution or triggers a specific behavior.
+
+      See also :term:`Argument`.
+
+   Package
+      In Python context, a directory containing one or more Python modules.
+      The Python interpreter treats a directory as a regular package if it contains a :file:`__init__.py` file.
+
+      See also :term:`Module`
+
+   Parallelism
+      The simultaneous execution of multiple tasks at the exact same instant, which requires a system with multiple hardware resources like CPU cores.
+
+      *Parallelism* is about executing multiple tasks simultaneously. This requires multiple CPU cores
+
+      See also :term:`Concurrency`
+
    PEP
       *Python Enhancement Proposal (PEP)* are design documents that
       describe a new feature for Python and documenting the design decisions.
@@ -97,7 +156,7 @@ Glossary
       reStructuredText (reST or RST) files into various output formats
       such as HTML, PDF, or manual pages or more.
 
-      See :ref:`build-docs`.
+      See section :ref:`build-docs`.
 
    UV
       A fast package manager which simplifies the building, installing,
@@ -118,7 +177,7 @@ Glossary
       By convention, a project's VENV is stored in a directory
       named :file:`.venv` located at the root of the project folder.
 
-      See :ref:`prepare-devel-env`.
+      See section :ref:`prepare-devel-env`.
 
    XML
       The *eXtensible Markup Language* is a text-based markup

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Add project dependencies, add link to ``susedoc/docserv-config`` repo, and amend the glossary