SUMA enterprise docs D.S.C.

Publishing to documentation.suse.com

Table of Contents

• Requirements for publishing
• Configuring SUSECOM playbook files
• Build the docs for D.S.C
  • 4.2 PDF
  • 4.1 PDF
  • 4.0 PDF
  • Build SUMA HTML API docs
    • Requirements
    • Build the API docs (4.2 only)

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

1. 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/

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

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

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

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

3. Run the following command to setup the correct parameters:

   make configure-suma

4. Run the following command to build the docs including translations (requires po4a):

   make antora-suma

5. The contents of the build/ dir should be dropped into the target version directory.

   

   Figure 1. 4.2 Directory Example

4.2 PDF

1. 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.

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

3. Extract the XML file:

4. 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

1. Enter the rpm directory:

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

1. 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

1. Drop the pdf document into link:https://gitlab.suse.de/susedoc/docserv-external-tree-suma/VERSION/PDF

2. Submit a merge request for Julio, Stefan or Frank.

4.1 PDF

1. 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.

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

3. Extract the XML file:

4. 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

1. Enter the rpm directory:

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

1. 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

1. Drop the pdf document into link:https://gitlab.suse.de/susedoc/docserv-external-tree-suma/VERSION/PDF

2. Submit a merge request for Julio, Stefan or Frank.

4.0 PDF

1. 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.

2. Use the Download button next to a spacewalk-java-apidoc-sources-4.0.21-1.1.noarch.rpm.

3. Extract the XML file:

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

1. 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

1. Drop the pdf document into link:https://gitlab.suse.de/susedoc/docserv-external-tree-suma/VERSION/PDF

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

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

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

3. 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.

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

5. Extract the asciidoc files:

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

6. Enter the rpm directory:

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

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

8. 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

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

   make antora-suma

10. Copy the build/ contents into our gitlab repo at:

    • https://gitlab.suse.de/susedoc/docserv-external-tree-suma/-/tree/master/4.2/api

11. Create a merge request and ping Julio, Stefan or Frank.

For more topics on building documentation, see Building documentation.