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.

4.1

• Click https://build.suse.de/package/binaries/SUSE:SLE-15-SP2:Update:Products:Manager41/spacewalk-java/standard. If it does not work, click https://build.suse.de/project/show/SUSE:SLE-15-SP2:Update:Products:Manager41 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:

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

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

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

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