uyuni community project docs

Publishing to uyuni-project.org

Table of Contents

• Building UYUNI Community Docs
  • Requirements
  • Verify WebUI playbook file attributes
  • Build the Static HTML from source
  • Preparing the Database Schema content
  • Preparing Uyuni API documentation

Building UYUNI Community Docs

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 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: "2024.01"
         - attribute: docversion
           value: "2024.01"
         - attribute: minorversion
           value: "2024.01"

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 for further clarification.

   asciidoc:
     - attribute: opensuse-version
       value: 15.5
     - 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

2. Backup your new build:

   cp -R build/ ../uyuni-2024.01

3. Clean up your build:

   make clean

4. Checkout the gh-pages branch:

   git checkout gh-pages

5. Update your local checkout:

   git pull

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

   git checkout -b gh-pages-uyuni-2024.01

7. Copy the contents of your build directory backup into the new release branch.

8. 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 build.opensuse.org

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

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

4. Untar it.

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

6. If you have not checked it out previously checkout the gh-pages branch.

   git checkout gh-pages

7. Add the contents of the untarred directory to the gh-pages/reporting-db-schema branch/directory. Do not remove the .nojekyll file from the gh-pages checkout. This will break this 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 -am "gh-pages update for uyuni-2024.01"
   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 and hand it off to @rel-engineers on Slack.

Preparing Uyuni API documentation