DOCSEARCHbyAlgolia
Submit Docs

Uyuni and SUSE Multi-Linux Manager Documentation Toolchain

website·Indexed 29 days ago

https://susedoc.github.io/Uyuni-Docs-Architecture/

A comprehensive guide to the documentation ecosystem for Uyuni and SUSE Multi-Linux Manager. It covers the Docs-as-Code toolchain, including the use of AsciiDoc, Go, Task, and containerized build environments. The documentation includes processes for issue handling, agile methodology, branch conventions, GitHub Actions, and packaging documentation RPMs via the Internal Build Service (IBS).

Tokens
17.9K
Snippets
110
Records
157
Agent score
75%

What's inside Uyuni

  1. Overview of the legacy Uyuni Documentation Helper

    The uyuni-docs-helper script and associated Make targets are used to build Uyuni documentation for older branches (such as manager-4.3 and manager-5.0). It provides a consistent build environment via containers to avoid manual installation of numerous dependencies. Note: For current master builds, use the modern Container setup (task container:build).

  2. Overview of the Uyuni and SUSE Multi-Linux Manager documentation toolchain

    The Uyuni and SUSE Multi-Linux Manager documentation ecosystem uses a specific set of tools for content creation, build/publishing, and localization. It is designed to support both the open-source Uyuni platform and the enterprise SUSE Multi-Linux Manager solution.

  4. Manage Uyuni documentation translations via Weblate

    Uyuni documentation translations are managed using Weblate. Note that Multi-Linux Manager versions 5.1 and 5.2 are not connected to Weblate; instead, Vistatek maintains forks of those release branches, performs AI translation, and submits pull requests to update the translation files.

  5. Use Go in the Uyuni documentation toolchain

    Go is utilized within the documentation toolchain to handle generated content, helper utilities, and Task-based automation. Specifically, the cmd/docbuild tool in the uyuni-docs repository is used to generate Antora configuration files from a config.yml source.

  6. SUSE Manager documentation update flow and lifecycle

    The repository follows a specific flow for different types of changes:

    • New Features: Developed on feature branches $\rightarrow$ merged to master $\rightarrow$ backported to active major release branches if applicable.
    • Bug Fixes: Applied to the relevant maintenance update branch $\rightarrow$ merged to the major release branch $\rightarrow$ cherry-picked to master if applicable.
    • Security Updates: Applied to all active maintenance branches and deployed to all supported versions simultaneously.

    Branch Lifecycle: Maintenance branches are short-lived; they are merged back into the major release branch after the update is released and then archived.

  7. Validate and test GitHub Actions workflow updates

    After updating a workflow file, perform the following validation steps to ensure the YAML is correct and the workflow triggers as expected.
    # 1. Validate YAML syntax
yamllint .github/workflows/filename.yml

# 2. Commit and push changes
git add .github/workflows/
git commit -m "Add SUSE Multi-Linux Manager 5.2 to GitHub Actions workflows"
git push

  8. Update sequence for SUSE Manager documentation workflows

    When introducing a new major release, update the GitHub Actions workflow files in the following recommended order to ensure stability and incremental verification:

    1. Development builds (build_and_archive_devel_docs.yml): Add the new major branch immediately and test with a sample commit.
    2. Translation updates (update_translation_files.yml): Add the major branch and Maintenance Update (MU) patterns.
    3. PDF translation testing (test_pdf_translations.yml): Add the new branch and verify PDF generation.
    4. Release builds (build_and_archive_release_docs.yml): Add complete release cycle patterns (this is the most complex update).

  9. Localize and translate Uyuni and SUSE Multi-Linux Manager documentation

    Translation workflows differ by product:

    • Uyuni: Uses Weblate for documentation translations.
    • SUSE Multi-Linux Manager (5.1 and 5.2): Uses a Vistatek fork and AI-driven translation Pull Requests (PRs).

  10. Configure release branch and maintenance patterns for MLM documentation

    To support the full release cycle (alpha, beta, RC, GMC, GM, and maintenance updates) for a new SUSE Multi-Linux Manager version, update the build_and_archive_release_docs.yml workflow located at .github/workflows/build_and_archive_release_docs.yml. You must add regex patterns to match the various release stages and maintenance update numbers.
    name: Build and archive documentation from release branches

on:
  push:
    branches:
      - 'uyuni-20[0-9][0-9].[0-9][0-9]'
      - 'manager-5.0'
      - 'manager-5.0-MU-5.0.[0-9][0-9]?'
      - 'manager-5.2-alpha[0-9]'                  # ADD: 5.2 alpha releases
      - 'manager-5.2-beta[0-9]'                   # ADD: 5.2 beta releases
      - 'manager-5.2-rc[0-9]'                     # ADD: 5.2 release candidates
      - 'manager-5.2-gmc[0-9]'                    # ADD: 5.2 GMC releases
      - 'manager-5.2-gm'                          # ADD: 5.2 gold master
      - 'manager-5.2'                             # ADD: 5.2 final release
      - 'manager-5.2-MU-5.2.[0-9][0-9]?'         # ADD: 5.2 maintenance updates

  11. Integrate VS Code with WSL2 for documentation development

    Using the 'Remote - WSL' extension allows you to edit files in the Linux filesystem while executing commands natively in the WSL environment. Install the extension on Windows, then use the Command Palette (F1) to connect to your specific distribution.
    # Install the Remote-WSL extension
code --install-extension ms-vscode-remote.remote-wsl