Skip to content

building uyuni docs

Jump to bottom
Karl Eichwalder edited this page Nov 13, 2023 · 6 revisions

Building Uyuni Docs

Branch conventions

Procedure: Configuring UYUNI docs for publishing

We use the following version conventions for publishing for all targets.

  1. Create a new branch from master for this release, and push it:

    git checkout -b uyuni-yyyy.mm        // yyyy = year, mm = month

git push

Building UYUNI OBS packages

Requirements for building

  • You have the SUSE Open build service tools setup on your local machine, and you have an account at build.suse.org. For more information on configuring OBS see the OBS Tutorial.

  • Our documentation tool chain should be installed. See: Toolchain Installation

WEBUI playbook files

  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.

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

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

    asciidoc:
  attributes:
    productname: 'Uyuni'
    productnumber: '2021.07'
    docversion: '2021.07'
    minorversion: '2021.07'
    saltversion: 3002
    sles-version: 15
    sp-version: sp3
    sp-vert: sp3 # use for terminal block
    sp-version-l: sp3
    smrproductnumber: 4.2
    opensuse-version: 15.3

  3. Check the following attributes in the branding/pdf/entities.adoc ensuring the file version numbers are correct:

    :productnumber: 2021.07
:docversion: 2021.07
:saltversion: 3002
:sles-version: 15
:sp-version: SP3
:sp-version-l: sp3
:opensuse-version: 15.3

  4. Select the following ui.bundle key using comments webui-branding-2020-default_ui.zip and ui.supplemental_files webui-branding-2020.

    ui:
  bundle:
    url: ./branding/default-ui/suma/latest-bundle.zip
    snapshot: true

  supplemental_files: ./branding/supplemental-ui/uyuni/uyuni-webui

Build the packages

  1. Build the OBS packages. From the local checkout directory on the command line run:

    example
    make obs-packages-uyuni

  2. Once packages are built configure the correct environment variables for OBS:

    example
    OBS_USER=keichwa
OBS_USER=jcayouette
OBS_USER=omaric

  3. Add the target OBS repo. For Uyuni, use:

    example
    OBS_REPO=systemsmanagement:Uyuni:Master

  4. Checkout the docs package from OBS:

    osc -A https://api.opensuse.org bco $OBS_REPO uyuni-docs_en

    If this fails with a 404, login to your account at https://build.opensuse.org and try again.

  5. Copy the two new packages located in build/packages into:

    build/home:$OBS_USER:branches:$OBS_REPO/uyuni-docs_en

  6. Change into the OBS checkout dir:

    cd home:$OBS_USER:branches:$OBS_REPO/uyuni-docs_en

  7. Create the changes files. You need to have the exact same changes in two files.

    For Uyuni, they are named:

    • uyuni-docs_en.changes

    • uyuni-doc-indexes.changes

    osc vc uyuni-docs_en.changes

  8. Copy the changes from the .changelog file under the timestamp, and save. release number as the top entry in both files. It should look something like this:

    example
    -------------------------------------------------------------------
Wed July 7 15:16:07 UTC 2021 - Joseph Cayouette <[email protected]>

- Version 2021.07   <---- BUMP VERSION
- Updated wording for prometheus section
- Jeos VM update
- Port 8050 for graphical console display
- Content life-cycle docs are not enough for customer to understand (bsc#1137955)
- Salt boot formula fails for SLES11 SP3 terminal (bsc#1136857)
- Certificate verify failed when using vmware esxi virtual host gatherer (bsc#1136561)

-------------------------------------------------------------------

  9. Repeat for the other file:

    osc vc uyuni-doc-indexes.changes

    Make sure the changes are exactly the same! The changes files must be located in the build/home:$OBS_USER:branches:$OBS_REPO/susemanager-docs_en directory, along with the package files you created earlier.

  10. For Uyuni, you need to update the version release number in the .spec files. Open the following files in your text editor, and update the Version: entry (around L19) with the version you are preparing:

    • uyuni-docs_en.spec

    • uyuni-doc-indexes.spec

      example
      Name:           uyuni-doc-indexes
Version:        2020.06
Release:        0

      Save the files.

  11. Check in the changes. This will also start the build:

    osc ci -m "update"

  12. It will take about 15 minutes for all the packages to build. You can check the build results in your home project; e.g. with:

    osc pr

    Alternatively, you can go to the OBS site to monitor progress.

  13. Once you are certain that doc packages are building properly on OBS submit an service request to Julio (After a successful review he will accept the service request, and the docs will be included in the new RPM’s.):

    osc sr -m 'update'

Publishing Uyuni Documentation to ghpages

Publishing Uyuni API Docs

Requirements

  • You have the SUSE Open build service tools setup on your local machine, and you have an internal account at build.opensuse.org. For more information on configuring OBS see the OBS Tutorial.

  • Our documentation tool chain should be installed. See: Toolchain Installation

Build the Uyuni API docs (HTML)

The following guide will walk you through updating API content at: http://www.uyuni-project.org/uyuni-docs-api/uyuni/index.html . Clone our API docs repository at: https://github.com/uyuni-project/uyuni-docs-api

  1. Create a new branch from master for this release:

    git checkout -b uyuni-api-yyyy.mm-beta       // for development

git checkout -b uyuni-api-yyy.mm              // for major release

git push

  2. On OBS search for https://download.opensuse.org/repositories/systemsmanagement:/Uyuni:/. Click Repositories, then one of the standard links.

  3. Use the Download button next to a spacewalk-java-apidoc-sources-{VERSION}.noarch.rpm.

  4. Extract the asciidoc files:

    unrpm -v spacewalk-java-apidoc-sources-VERSION.noarch.rpm

  5. Enter the rpm directory:

    cd usr/share/doc/packages/spacewalk-java/asciidoc/

  6. Open either the apilist.adoc or the xml file from asciidoctor/docbook sources and verify the version number before building

  7. Drop the adoc files into your local clone located:

  8. After verifying the index and api nav lists match the current calls build the api docs with:

    make antora-suma

  9. Copy the build/ contents to a temporary location.

  10. Checkout the ghpages branch: git checkout gh-pages

  11. Create a new PR branch for gh-pages: git checkout -b uyuni-api-yyyy.mm

  12. Create a merge request and ping Julio or Jordi.

uyuni logo

Uyuni Docs

Clone this wiki locally