Skip to content

prepare-environment.rst

Latest commit

 

History

History
121 lines (75 loc) · 4.18 KB

prepare-environment.rst

File metadata and controls

121 lines (75 loc) · 4.18 KB

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 :file:`.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:

.. graphviz::
   :name: fig-high-level-overview
   :align: center
   :caption: High-level project overview

   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"];
   }

GitHub CLI

GiHub CLI is a command-line tool named :command:`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 :ref:`prepare-installation` and :ref:`installing-docbuild`.

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

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

    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 :file:`devel/activate-aliases.sh` to abbreviate the longer :command:`uv` calls (see :ref:`devel-helpers` for more information):

    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.