Preparing Your Development Environment#

This document provides instructions for setting up a development environment for this project.

Note: A Quick Word on Virtual Environments

The uv tool can work with or without activating a Python virtual environment (venv). When uv finds a .venv directory, it uses it automatically. There is no need to “activate” it. However, if you get used to activating your Python VENV’s, it’s possible to do so.

High-level project overview#

The following diagram illustrates the relationship between the main components of the project:

digraph "Project Components" { rankdir="LR"; node [shape=box, style="rounded,filled", fillcolor="#E6F2FF"]; "pyproject" [label="pyproject.toml\nConfiguration"]; "uv" [label="uv\nPackage Manager"]; "src" [label="src/\nSource Code"]; "tests" [label="tests/\nTests"]; "docs" [label="docs/ and changelog.d/\nDocumentation"]; "towncrier" [label="towncrier\nChangelog Tool"]; "pyproject" -> "uv" [label="configures"]; "uv" -> {"src", "tests", "docs"} [label="manages dependencies for"]; "towncrier" -> "docs" [label="generates changelog in"]; }

High-level project overview#

Helper Tools#

The directory devel/ contains some helper tools to make development easier:

  • activate-aliases.sh

    Activates helpful aliases for the development environment. You need the uv command. It provides shortcuts for common commands:

    • docbuild

      The project’s main command.

    • makedocs

      Builds the project’s documentation.

    • towncrier

      Manages changelog and news entries.

    • upytest

      Runs the project’s test suite through pytest.

    • uipython

      Starts an interactive IPython shell using start-up scripts in the .ipython/ directory.

    It is recommended to enable the aliases in your shell by sourcing the shell script from the root directory of the project:

    Activating development aliases#
    source devel/activate-aliases.sh
  • bump-version.sh

    Bumps the version of the project. To bump the minor version, use bump-version.sh minor.

  • lines-of-code.sh

    Prints a summary of code lines, comments, and blank lines in the project for each file type.

In this documentation, we will use the aliases from now on.

GitHub CLI#

GiHub CLI is a command-line tool named gh that 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.

Setting up the development environment#

The following steps are recommended to set up your development environment:

  1. Follow the steps in Preparing for Installation and Installing the tool.

  2. If you haven’t created a virtual environment, do so:

    Creating a virtual environment with uv#
    uv venv --prompt venv313 --python 3.13 .venv

    Keep in mind that the Python version used in the virtual environment should match the version specified in the pyproject.toml file.

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

    Synchronizing the virtual environment with the development dependencies#
    uv sync --frozen --group devel

    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 devel/activate-aliases.sh to abbreviate the longer uv calls (see Helper Tools for more information):

    Activating the shell aliases for development#
    source devel/activate-aliases.sh

After completing these steps, your development environment is ready to go.

Getting Docserv’s Config Files#

The docbuild tool relies on a central set of XML configuration files to build SUSE product documentation. These files, which define all products, docsets, and their deliverables, are managed in the susedoc/docserv-config repository.

To get started, clone this repository to your local machine (you need VPN access):

git clone https://gitlab.suse.de/susedoc/docserv-config.git

You will later need to point docbuild to the location of this cloned repository in your configuration.