Publishing to documentation.suse.com

Publishing to documentation.suse.com (D.S.C)

Table of Contents

• Introduction
• Building SUMA HTML with the uyuni-docs-helper
  • Requirements
  • Configuring parameters for D.S.C
    • Remote Build
    • Local Build
  • Configuring Parameters
  • Build the HTML
  • Updating content on GitLab.suse.de
  • Updating API docs on D.S.C
    • Troubleshooting
    • Prepare API Merge Request for D.S.C
  • Update DBSchema Docs for D.S.C
  • Inform release managers
• Navigation

❗	TBD: Should this document be moved to Confluence?

Introduction

This document describes the process of preparing the documentation for publishing on D.S.C (documentation.suse.com).

The output of the process are up to ?? separate PRs/MRs (TBD: list them all here, link to examples).

TBD: The PRs / MRs need to:

• Happen in the exact order in which they are described (or not?)

• Are (not?) awaiting other processes to finish (e.g. packages to be built…​)

Building SUMA HTML with the uyuni-docs-helper

Requirements

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

• You have access to the our internal https://gitlab.suse.de repository Docserv External Tree SUMA with write access

Configuring parameters for D.S.C

D.S.C. refers to documentation.suse.com. See SUMA Documentation.

Remote Build

For a remote build, you need to adjust the parameters.yml file for your target (Static HTML for D.S.C).

If you are using the uyuni-docs-helper image to build from the remote source, make the following example changes to your local uyuni-docs/ checkout and then push them to the remote repository on GitHub. Then follow the remote build commands below.

Local Build

If you are using the uyuni-docs-helper image to build from your local git checkout, modify the local parameters.yml file and then follow the local build commands below.

Configuring Parameters

1. Ensure you are on the correct branch, then open parameters.yml in your editor of choice.

   ⚠️	While working on the parameters file make sure that you adjust the SUMA section and not the Uyuni section.

   Example

       site:
         - attribute: title
           value: "SUSE Manager Documentation"
         - attribute: start_page
           value: "suse-manager::index"
         - attribute: url
           value: https://documentation.suse.com/suma/5.0/

2. Check the following block in parameters.yml ensuring the version numbers are correct. The yaml or attributes themselves should not be adjusted. Only the version numbers should be adjusted:

   Example

     suma:
       asciidoc:
         - attribute: productnumber
           value: "5.0"
         - attribute: docversion
           value: "5.0"
         - attribute: minorversion
           value: "5.0"

3. Fix the supplemental_files value for the SUMA susecom so it looks like:

         supplemental_files: ./branding/supplemental-ui/suma/susecom-2023

4. Push your changes to the remote repository release branch.

Build the HTML

There are two methods to build the packages from the uyuni-docs-helper directory. You can build either from a remote source or a local repository clone. Select one of the following two methods:

Remote build

The following command builds the docs from the remote repository.

Example

./uyuni-docs-helper -r manager-x.y-MU-x.y.z -o ./tmp -c antora-suma -p suma

Local build

The following command builds the docs from the local uyuni-docs checkout:

Example

./uyuni-docs-helper -l ../uyuni-docs -r manager-x.y-MU-x.y.z -c antora-suma -p suma

Updating content on GitLab.suse.de

Have you cloned the gitlab.suse.de repo? Within this repo, the following directory structure exists:

docserv-external-tree-suma

4.3/
5.0/

1. Pull the latest changes from master.

2. Create a copy of the build directory (the content you just created with make antora-suma) containing the generated html and put it somewhere safe.

3. Create the merge branch for the current release, e.g.:

   git checkout -b manager-5.0-MU-5.0.1

   • TBD: Alternatively, name the branch manager-5.0-MU-5.0.1-HTML to specifically reflect its purpose. Follow this convention with all other branches.

4. Overwrite the content in the 5.0/ directory with the content from your latest build.

5. Push the new branch

6. On gitlab, create the merge request with master.

Updating API docs on D.S.C

This section assumes you have cloned the Uyuni Docs API Repository (i.e. uyuni-project /uyuni-docs-api).

1. Pull the latest changes from master

2. Checkout your feature branch:

   git checkout -b manager-5.0-content-update

3. Grab the latest spacewalk-java-apidoc-sources rpm.

   • https://download.suse.de/ibs/Devel:/Galaxy:/Manager:/head/SLE_15_SP4/noarch/

4. For newer SUMA versions (5.0 and later) use:

   • https://download.suse.de/ibs/Devel:/Galaxy:/Manager:/5.0/SLE_15_SP6/noarch/

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

6. 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. (TBC: What happens IF there are differences?)

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

8. create a merge request with master and merge (TBC: 1. MR or PR? 2. No need to wait for approval?)

9. switch to the master branch.

10. Build the API documents with make antora-suma (TBC: Why now? What are we expecting as an outcome, what is a possible issue?)

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 intelligent logic like our uyuni-docs repo. When you build from your local system, the command make antora-suma 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 this index-not-found error.

Prepare API Merge Request for D.S.C

1. Create a new feature branch on the docserv-external-tree-suma repository for the merge request. For example:

   git checkout -b manager-4.3-MU-4.3.11-api

2. Copy the build contents into docserv-external-tree-suma/4.3/api/ (TBC: From the build above / see question why now / what it is used for)

3. Cut the API PDF to 4.3/pdf/ and rename it to match the existing document 4.3_pdf_susemanager_api_doc_color_en.pdf

4. Add, commit and push your feature branch.

5. Create the merge request and merge with master.

Update DBSchema Docs for D.S.C

We provide database schema documentation when we publish to documentation.suse.com. To update the database scheme documentation perform the following steps.

1. Log in to build.suse.de

2. Go to the project of interest, for example:

   • Devel:Galaxy:Manager:5.0/susemanager-docs-en SUMA 5.0

   • Devel:Galaxy:Manager:4.3/susemanager-docs_en SUMA 4.3

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

4. Untar it.

5. on the command line go to your local docserve-external-tree-suma checkout.

6. Create a new feature branch from master (make sure you pull the latest changes! TBD: new featrure as in 5.0.-MU-5.0.1, or 5.0-MU-5.0.1-DBschema?).

7. On your featuuree branch, copy the contents of the new dbschema directory (TBC: the one you just got by unpacking the downloaded package) into your target product version directory: docserve-external-tree-suma/4.3/database/schema/

8. Submit your merge request and then merge with master.

Inform release managers

1. Merge above created MR with master

2. Inform release managers that content (New docs, API, and dbschema) has been merged with DocServ.

Release managers will make the sync request to the SUSE Documentation team when they are ready to release the latest major or minor version to the public.

Navigation

1. Previous: Packaging internal build service docs

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