Installing docbuild

To install the docbuild tool, follow these steps:

1. Preparing for Installation - Prepare your environment for installation.

2. Installing the tool - Install the docbuild tool itself.

3. Getting the XML configuration - Get the XML configuration files required for building documentation.

4. Configuring the Tool - Configure the docbuild tool to suit your needs.

Preparing for Installation

It is highly recommended to use the package and project manager uv to install the docbuild tool. This ensures that all dependencies are managed correctly and that the installation is reproducible across different environments.

There are different methods to install the uv package manager (see Installing uv). In this case, use the standalone installer:

1. Install uv

   Run the following command in your terminal:

   curl -sSfL https://astral.sh/uv/install.sh | sh
   

   This will install two commands uv and uvx in ~/.local/bin/. Make sure this directory is in your PATH environment variable.

2. Check the installation

   After the installation, verify that uv is installed correctly by running:

   type uv
   uv is hashed (/home/tux/.local/bin/uv)
   uv --version
   ...
   

   You should see the version of uv printed in the terminal.

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 uv:

   uv python install 3.13
   

   The previous command downloads Python 3.13 and install it in the directory ~/.local/share/uv/python/<VERSION>.

4. Check the available Python versions

   To see the installed Python versions, run:

   uv python list
   cpython-3.14.0b1-linux-x86_64-gnu                 <download available>
   cpython-3.14.0b1+freethreaded-linux-x86_64-gnu    <download available>
   cpython-3.13.4-linux-x86_64-gnu                   /home/tux/.local/share/uv/python/cpython-3.13.4-linux-x86_64-gnu/bin/python3.13
   [...]
   

   You should see Python 3.13 listed among the available versions.

Installing the tool

1. Clone the repository

   Open your terminal and run the following command to clone the docbuild repository from GitHub:

   git clone https://github.com/openSUSE/docbuild.git
   cd docbuild
   

2. Create a virtual environment

   It is recommended to create a virtual environment to isolate the docbuild tool and its dependencies from your system Python environment. Run the following command:

   uv venv --prompt "venv313" .venv
   

   This will create a virtual environment in the directory .venv.

4. Install dependencies

   Ensure you have Python 3.12 or higher installed, then install the required dependencies using pip:

   uv sync --frozen
   Resolved 29 packages in 586ms
   Built docbuild @ file:///.../docbuild
   Installed 15 packages in 2.11s
   

   The –frozen flag is used here to ensure that uv installs dependencies exactly as specified in the uv.lock file. This is crucial for reproducible builds and maintaining a consistent environment across different machines or deployments, as it prevents uv from attempting to resolve and potentially update dependency versions.

Getting the XML configuration

Formerly known as the Docserv XML configs. These configuration files defines the products, their releases, their 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://susedoc/docserv-config to your machine where you can access it easily. As an alternative, use the RNC schema <https://www.oasis-open.org/committees/relax-ng/compact-20021121.html>_ from src/docbuild/config/xml/data/ to create your own configuration.