Skip to content

building suma docs

Jump to bottom
Jcayouette edited this page Mar 28, 2023 · 8 revisions

Building SUSE Manager Docs

Branch conventions

Procedure: Configuring SUMA docs for publishing

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

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

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

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

  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.

    translations guide
    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:

  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:

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

uyuni logo

Uyuni Docs

Clone this wiki locally