building suma docs

Building SUSE Manager Docs

Table of Contents

Branch conventions
Building SUMA IBS packages
Publishing for documentation.suse.com

Branch conventions

Procedure: Configuring SUMA docs for publishing

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

Create a new branch from master for a major or minor release, and push it:

git checkout -b manager-x.y-betax        # for development

git checkout -b manager-x.y              # for major release

git push

Create a new branch from manager-x.y for a maintenace update (MU), and push it:

git checkout -b manager-x.y-MU-x.y.z     // for a maintenance update

git push

Building SUMA IBS packages

Requirements

You have the SUSE Open build service tools setup on your local machine, and you have an internal account at build.suse.de. For more information on configuring OBS, see the OBS Tutorial.
Our documentation container should be setup. See: Container Setup and Use

Configuring `parameters.yml` for the product WEBUI

For both a local and remote build you need to adjust the parameters.yml file for your target. This means you will need to select the product ui theme for an IBS build.

When using the uyuni-docs-helper image you will first need to make these changes to your publishing branch, push them to the remote repository on GitHub then build with the remote as target. Otherwise you will not see your changes in the resulting build. If you are using your local git checkout of uyuni-docs modify the local parameters.yml file and follow the local build commands.
```
    site:
      - attribute: title
        value: "SUSE Manager Documentation"
      - attribute: start_page
        value: "suse-manager::index"
      - attribute: url
        value: /
```

Check the following attributes in the parameters.yml ensuring the file version numbers are correct:

  suma:
    asciidoc:
      - attribute: productnumber
        value: "4.3"
      - attribute: docversion
        value: "4.3"
      - attribute: minorversion
        value: "4.3.5"
      - attribute: saltversion
        value: 3004
      - attribute: sles-version
        value: 15
      - attribute:  sp-version
        value: SP4 #use for normal text
      - attribute: sp-vert
        value: sp4 #use for terminal block
      - attribute: sp-version-l
        value: sp4
      - attribute: smrproductnumber
        value: 4.2
      - attribute: opensuse-version
        value: 15.4

Select the following ui.bundle and supplemental_files values for the SUMA webui: Ensure that you adjust the suma block not the uyuni section.

    ui:
      bundle:
        - attribute: url
          value: ./branding/default-ui/suma/ui-bundle.zip
        - attribute: snapshot
          value: true
      supplemental_files: ./branding/supplemental-ui/suma/webui-2023

Build the packages

To build the packages from the uyuni-docs-helper local checkout run: ./uyuni-docs-helper -r manager-x.y-MU-x.y.z -o ./tmp -c obs-packages-suma-en -p suma. Ensure you have create the tmp directory in the checkout.
Once the packages are built configure your environment variables for OBS on the CLI:
example
```
OBS_USER=keichwa
OBS_USER=jcayouette
OBS_USER=omaric
```

Add the target repo. For SUMA point releases, this will be Devel:Galaxy:Manager:X.Y. For SUMA alpha and beta releases, use Devel:Galaxy:Manager:Head.

example

OBS_REPO=Devel:Galaxy:Manager:4.2      # Current maintained major release
OBS_REPO=Devel:Galaxy:Manager:4.3      # Current major release
OBS_REPO=Devel:Galaxy:Manager:Head     # Master branch

Checkout the docs package from OBS:

For SUSE Manager:
```
osc -A https://api.suse.de bco $OBS_REPO susemanager-docs_en
```
If this fails with a 404, go to the build.suse.de site and log in, then try again.
Copy the two new English packages located in build/packages into"
```
build/home:$OBS_USER:branches:$OBS_REPO/susemanager-docs_en*
```

Change into the OBS checkout dir:

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

Update the changes files using our changelog. Manager 4.2 and Manager 4.3 both use slightly different changelog update methods.

Manager 4.2 Changelog entries

You need to duplicate the changes in the two following files. (Including date and time)

For SUSE Manager, these are called:

susemanager-docs_en.changes
susemanager-doc-indexes.changes
```
osc vc susemanager-docs_en.changes
```
Copy the changes from the .changelog file under the timestamp, and save. It should look something like this:
susemanager-docs_en.changes
```
-------------------------------------------------------------------
Wed Jun 19 15:16:07 UTC 2019 - Joseph Cayouette <USER-EMAIL@suse.com>

- 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)

-------------------------------------------------------------------
```
1. Repeat for the other file:
  osc vc susemanager-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.
Save the files.
1. Check in the changes. This will also initiate the build:
  osc ci -m "update"
2. 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 or IBS site to watch progress.
3. Once you are certain doc packages are building properly on OBS submit an service request to Julio (If everything looks good he will accept and the docs will be included in the new RPM’s.):
  osc sr -m 'update'

Publishing for documentation.suse.com

Requirements for publishing

You have access to our internal gitlab repository.
Our documentation tool chain should be installed. See: Toolchain Installation

Configuring SUSECOM playbook files

From your local git checkout of uyuni-docs modify your parameters.yml file. Enable the site.url value key by removing the comment for your target:

example

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

Check the following attributes in the parameters.yml ensuring the file version numbers are correct:

example

  suma:
    asciidoc:
      - attribute: productname
        value: "SUSE Manager"
      - attribute: productnumber
        value: "4.2"
      - attribute: docversion
        value: "4.2"
      - attribute: minorversion
        value: "4.2.3"
      - attribute: suma-content
        value: true
      - attribute: uyuni-content
        value: false
      - attribute: saltversion
        value: 3002
      - attribute: sles-version
        value: 15
      - attribute:  sp-version
        value: SP3 #use for normal text
      - attribute: sp-vert
        value: sp3 #use for terminal block
      - attribute: sp-version-l
        value: sp3
      - attribute: smrproductnumber
        value: 4.2
      - attribute: opensuse-version
        value: 15.3

Select the correct ui.bundle key and ui.supplemental_files key. When building for D.S.C set the following :

example

    ui:
      bundle:
        - attribute: url
          value: ./branding/default-ui/suma/susecom-ui-branding-2021.zip
        - attribute: snapshot
          value: true
      supplemental_files: ./branding/supplemental-ui/suma/susecom-branding-2021

Build the docs for D.S.C

Checkout our internal gitlab repository: https://gitlab.suse.de/susedoc/docserv-external-tree-suma

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

git checkout -b manager-x.y-betax        // for development

git checkout -b manager-x.y              // for major release

git checkout -b manager-x.y-MU-x.y.z     // for a maintenance update

git push

Run the following command to setup the correct parameters:
```
make configure-suma
```
Run the following command to build the docs including translations (requires po4a):
```
make antora-suma
```
The contents of the build/ dir should be dropped into the target version directory.

Figure 1. 4.2 Directory Example

4.2 PDF

On IBS search for https://build.suse.de/repositories/Devel:Galaxy:Manager:4.2 and search for spacewalk-java. Click Repositories, then one of the standard links.
Use the Download button next to a spacewalk-java-apidoc-sources-{VERSION}.noarch.rpm.
Extract the XML file:
Open either the apilist.adoc or the xml file from asciidoctor/docbook sources and verify the version number before building.

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

Enter the rpm directory:

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

Build the PDF with daps: You must have daps installed to build

daps -vvv --styleroot="/usr/share/xml/docbook/stylesheet/suse2013-ns" -m susemanager_api_doc.xml pdf

Drop the pdf document into link:https://gitlab.suse.de/susedoc/docserv-external-tree-suma/VERSION/PDF
Submit a merge request for Julio, Stefan or Frank.

4.1 PDF

On IBS search for https://build.suse.de/repositories/Devel:Galaxy:Manager:4.1 and search for spacewalk-java. Click Repositories, then one of the standard links.
Use the Download button next to a spacewalk-java-apidoc-sources-{VERSION}.noarch.rpm.
Extract the XML file:
Open either the apilist.adoc or the xml file from asciidoctor/docbook sources and verify the version number before building.

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

Enter the rpm directory:

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

Build the PDF with daps: You must have daps installed to build

daps -vvv --styleroot="/usr/share/xml/docbook/stylesheet/suse2013-ns" -m susemanager_api_doc.xml pdf

Drop the pdf document into link:https://gitlab.suse.de/susedoc/docserv-external-tree-suma/VERSION/PDF
Submit a merge request for Julio, Stefan or Frank.

4.0 PDF

Click https://build.suse.de/package/binaries/SUSE:SLE-15-SP1:Update:Products:Manager40/spacewalk-java/standard. If it does not work, click https://build.suse.de/project/show/SUSE:SLE-15-SP1:Update:Products:Manager40 and search for spacewalk-java. Click Repositories, then one of the standard links.
Use the Download button next to a spacewalk-java-apidoc-sources-4.0.21-1.1.noarch.rpm.
Extract the XML file:

unrpm -v spacewalk-java-apidoc-sources-4.0.21-1.1.noarch.rpm

Build the PDF with daps:

daps --styleroot="/usr/share/xml/docbook/stylesheet/suse2013-ns" \
     -m usr/share/doc/packages/spacewalk-java/xml/susemanager_api_doc.xml \
     pdf

Drop the pdf document into link:https://gitlab.suse.de/susedoc/docserv-external-tree-suma/VERSION/PDF
Submit a merge request for Julio, Stefan or Frank.

Build SUMA HTML API docs

Requirements

You have the SUSE Open build service tools setup on your local machine, and you have an internal account at build.suse.de. For more information on configuring OBS see the OBS Tutorial.
Our documentation tool chain should be installed. See: Toolchain Installation

Build the API docs (4.2 only)

Clone our API docs repository at: https://github.com/uyuni-project/uyuni-docs-api

Create a new branch from master for this release:

git checkout -b manager-api-x.y-betax        // for development

git checkout -b manager-api-x.y              // for major release

git checkout -b manager-api-x.y-MU-x.y.z     // for a maintenance update

git push

On IBS search for https://build.suse.de/repositories/Devel:Galaxy:Manager:4.2 and search for spacewalk-java. Click Repositories, then one of the standard links.
Use the Download button next to a spacewalk-java-apidoc-sources-{VERSION}.noarch.rpm.

Extract the asciidoc files:

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

Enter the rpm directory:

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

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

Drop the adoc files into your local clone located:

https://github.com/uyuni-project/uyuni-docs-api/modules/api/pages

❗	For each release the API is updated with new functionality. Ensure that the list of calls contained in the RPM within apilist.adoc matches the list located in our api nav and index.adoc at the following locations: Root Index API Nav

After verifying the index and api nav lists match the current calls build the api docs with:
```
make antora-suma
```
Copy the build/ contents into our gitlab repo at:
- https://gitlab.suse.de/susedoc/docserv-external-tree-suma/-/tree/master/4.2/api
Create a merge request and ping Julio, Stefan or Frank.

Uyuni Docs

Home

building suma docs

Building SUSE Manager Docs

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uyuni Docs

Home

Doc squad

How to contribute

Packaging and publishing

Additional resources

Clone this wiki locally