Uyuni community project docs

Publishing to uyuni-project.org

Table of Contents

• Building Uyuni Community Documentation
  • Requirements
  • Verify WebUI playbook file attributes
  • Build the Static HTML from source
  • Preparing the Database Schema content
  • Preparing Uyuni API documentation
  • Merging the PRs
• Navigation

Building Uyuni Community Documentation

Last modified: January 25, 2023 10:05 CET

Requirements

You have uyuni-docs-helper container set up, see uyuni-docs-helper

Verify WebUI playbook file attributes

1. From your local git checkout of uyuni-docs in parameters.yml verify that the default value for site.url is enabled for uyuni-project.org. We support two outputs SUSE Manager ( MLM Manager) and Uyuni. Check that you are modifying the correct yaml block.

     uyuni:
       site:
         - attribute: title
           value: "Uyuni Documentation"
         - attribute: start_page
           value: "uyuni::index.adoc"
         - attribute: url
           value: https://www.uyuni-project.org/uyuni-docs/

2. Check the Uyuni version number in the parameters.yml. This should be adjusted to the release version.

       asciidoc:
         - attribute: productname
           value: "Uyuni"
         - attribute: productnumber
           value: "2025.05"
         - attribute: docversion
           value: "2025.05"
         - attribute: minorversion
           value: "2025.05"

3. Check the following attributes in the parameters.yml ensuring the file version numbers are correct. These numbers can be found in the OBS package spec files. For example: salt.spec. Feel free to ping release engineers (@multi-linux-manager-releng on channel #team-multilinux-manager-docs) for further clarification.

   asciidoc:
     - attribute: opensuse-version
       value: 15.6
     - attribute: saltversion
       value: 3006.0
     - attribute: postgresql
       value: PostgreSQL
     - attribute: postgresql-version
       value: 14
     - attribute: sles-version
       value: 15
     - attribute:  sp-version
       value: SP5 #use for normal text
     - attribute: sp-vert
       value: sp5 #use for terminal block
     - attribute: sp-version-l
       value: sp5

Build the Static HTML from source

1. Build the Static HTML. From the local checkout directory on the command line run:

   example

   make clean
   make configure-uyuni
   make antora-uyuni

   (This will take about 15 minutes)

2. Checkout the gh-pages branch:

   git checkout gh-pages

3. Update your local checkout:

   git pull

4. Create your new release branch for gh-pages:

   git checkout -b gh-pages-uyuni-2025.05

5. Copy the contents of your build/ directory into the root of the new release branch. cd build/ && cp -r . ../

6. Move onto the next step to add database schema content.

Preparing the Database Schema content

We provide database schema documentation when we publish to Database Schema. To update the database schema documentation perform the following steps.

1. Login to https://build.opensuse.org/

2. Go to the project of interest, for example: systemsmanagement:Uyuni:Master/uyuni-docs-en https://build.opensuse.org/project/show/systemsmanagement:Uyuni:Master

3. Download the reportdb-schema-docs.tar.xz file

4. Untar it.

5. On the command line go to your uyuni-docs checkout.

6. Checkout your gh-pages feature branch.

   git checkout gh-pages-your-branch

7. Add all the contents of the untarred directory to the gh-pages/reporting-db-schema directory.

   ❗	Do not remove the .nojekyll file from the gh-pages checkout, as this will break the publication! If you remove it, and notice something is wrong on the endpoint, add a new `.nojekyll file to the reporting-db-schema directory.

8. Push your local release branch.

   git add .
   git commit -m "gh-pages update for Uyuni-2025.05"
   git push

9. From the GitHub WebUI select the new branch you pushed for creating a PR.

10. IMPORTANT! Select gh-pages as the branch to merge into!

11. Create the pull request for gh-page, merge it. (TBD: Do we wait for the approval?)

12. Inform release engineers via Slack. Use @multi-linux-manager-releng on channel #team-multilinux-manager-docs.

Preparing Uyuni API documentation

This section assumes you have cloned the Uyuni Docs API Repository.

1. Pull the latest changes from master

2. Checkout your feature branch: git checkout -b uyuni-2025.05-API-content-update

3. Grab the latest spacewalk-java-apidoc-sources rpm. https://build.opensuse.org/ use the search bar to find: systemsmanagement:Uyuni:Master

4. Click the repositories tab

5. Under the latest leap release click the download repository button.

6. Select noarch then search for api.

7. Download the latest spacewalk-java-apidoc-sources-version-number.1.1.uyuni3.noarch.rpm (TBD: Version number is misleading. Change this.)

8. Untar the RPM and copy the contents of the asciidoc directory into your feature branch modules/api/pages/ directory.

9. Compare the content in modules/api/pages/apilist.adoc with modules/api/nav-api-guide.adoc and ensure no new API method calls have been added. It should be the developer`s responsibility to let us know about such changes.

10. Add, commit, and push your changes to your feature branch.

11. Create a PR content request with the master branch at the Uyuni-docs-api repository. Add a helpful description and a label in the form of API yyyy.mm and merge. (TBD: Does this means we don’t wait for approval, but we just merge it?)

12. Switch to the master branch. (TBD: Are we missing a step here to pull the latest changes before building in the next step?)

13. Build the API documents with make antora-uyuni

    ❗

    Troubleshooting If you run into issues with index-not-found errors, check the antora.yml file stored in the repository. You need to manually update this file to reflect which product you are building for. We do not yet have jinja2 logic as in our uyuni-docs repo. When you build from your local system, the command make antora-suma, make antora-mlm or make antora-uyuni will always look at this antora.yml file. If the wrong product is commented out (for the command you input), Antora will throw the index-not-found error.

14. Once content is built, store the contents of the build directory someplace safe.

15. Checkout the gh-pages branch and create your new uyuni-2025.05-api-gh-pages feature branch.

    git checkout gh-pages
    git checkout -b uyuni-2025.05-api-ghpages

16. Overwrite content in the directory uyuni/api with the new API content (previously saved from the build you had run).

17. Do not remove the .nojekyll file. It is used by GitHub to properly publish our sources.

18. Add the changes, commit and push your new branch with the content update.

19. Create your PR against gh-pages. It needs to be approved by someone other than its author before proceeding with the next step.

    ❗	Make sure that you are merging the api-ghpages branch into gh-pages and NOT MASTER

20. Inform release engineers via Slack. Use @multi-linux-manager-releng on channel #team-multilinux-manager-docs and provide the PR URL.

Merging the PRs

Do not merge the approved PRs until you are notified by the release managers that the release is complete.

Navigation

1. Previous: Packaging for the Open Build Service

2. Up: For more topics on building documentation, see Building documentation