Publishing API Documentation Online

Updating SUSE Manager API Documentation and Posting Online

The XML source file of the API documentation is packaged as spacewalk-java-apidoc-sources-VERSION.noarch.rpm and stored in the internal Build Service. You must log in the Build Service to download this package. From the XML source file we build the PDF to be published on suse.com. Here are instructions for SUSE Manager 3, 3.1, 3.2 (SLE 12 SP1, SP2, and SP3), 4.0 (SLE 15 SP1), 4.1 (SLE 15 SP2).

Step 0: Click https://build.suse.de, and log in. Save the cookie!

When downloading the following packages ensure you have the correct MU version. In noarch there are several versions. Each one is released during a specific MU window. It is important to use the correct MU version when packaging for said MU version of the API docs. For example 4.1.4 docs were released in December so you would select this dated version of the package.

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

4.0

• 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

• Copy the PDF to gitlab's external-tree directory and ping the docserv maintainers (Stefan, Frank).

3, 3.1, 3.2 (SLE 12 SP1, SP2, and SP3 example)

# rename existing directory
old binaries

# checkout the official binary packages
# The following getbinaries command is for SUSE Manager 3.0 
iosc getbinaries SUSE:SLE-12-SP1:Update:Products spacewalk-java standard x86_64

# SUSE Manager 3.1 is based on SLES12-SP2; download spacewalk-java-apidoc-sources-*.noarch.rpm, e.g.:
# You can get the package directly from the correct repository.
http://download.suse.de/ibs/SUSE:/SLE-12-SP2:/Update:/Products:/Manager31:/Update/standard/noarch/spacewalk-java-apidoc-sources-2.7.46.18-2.38.1.noarch.rpm

# SUSE Manager 3.2 is based on SLES12-SP3; download spacewalk-java-apidoc-sources-*.noarch.rpm, e.g.:
# You can get the package directly from the correct repository.
http://download.suse.de/ibs/SUSE:/SLE-12-SP3:/Update:/Products:/Manager32:/Update/standard/noarch/spacewalk-java-apidoc-sources-2.8.78.13-3.13.1.noarch.rpm

# unpack the docbook file
unrpm -v binaries/spacewalk-java-apidoc-sources*
# or:
unrpm -v http://download.suse.de/ibs/SUSE:/SLE-12-SP3:/Update:/Products:/Manager32:/Update/standard/noarch/spacewalk-java-apidoc-sources-2.8.78.13-3.13.1.noarch.rpm
# ==>
# usr/share/doc/packages/spacewalk-java/xml/susemanager_api_doc.xml

# build the PDF with daps (with --styleroot, this is very slow):
daps --styleroot="/usr/share/xml/docbook/stylesheet/suse2013-ns" \
  -m usr/share/doc/packages/spacewalk-java/xml/susemanager_api_doc.xml pdf