Building YumaPro Documentation

Documentation Introduction

Online Documentation

The YumaPro documentation set can be found online at docs.yumaworks.com. It is hosted by Read The Docs.

The latest version of the YumaPro Doxygen Reference is also available.

Both these WEB sites can be built and access from a local disk or WEB server by building the WEB pages.

The yumapro/doc Directory

The documentation can also be built from the source distribution. All current and old documentation is maintained in this directory. Only the 'newdoc' build procedure is used now.

Note

  • There is only two versions of the documentation maintained at this time.

  • Only the latest release train is available online.

  • Currently the 23.10 and 23.10T release trains can be used to build the documentation for that release train.

About YumaPro 'newdoc'

../_images/yumapro-doc-tools.png

Older versions of YumaPro used the LibreOffice ODT file for documentation. These files are no longer maintained. The online documentation now provides the authoritative and most updated version of the documentation. Version specific features and APIs are noted in the 'History' portion of each API section.

All documentation is now written in Restructured Text (RST).

All server H files are fully documented with Doxygen headers. The SDK documentation is generated directly from the source code as much as possible.

Install Documentation Dependencies

There are several tools which must be installed correctly in order to build the documentation. There may be more than listed here, including the fantastic Pygments syntax highlighter (which should be installed automatically).

Doxygen

Install doxygen.

For example, on Ubuntu the command would be:

> sudo apt-get install doxygen

It is very important that the correct version of doxygen be used.

Note

  • The doxygen versions installed on Ubuntu 20.04 and 22.04 are broken.

  • The doxygen version on Ubuntu 18.04 is not broken and will work.

  • The XML output is incorrect and the 'breathe' program cannot generate HTML correctly when the Sphinx output is generated.

  • It is suggested that Doxygen version 1.9.5 be built from sources

  • The latest version 1.10.0 does not work.

Python3

The Python 3 tools must be installed. This is usually already installed so instructions are not given here. On Ubuntu, the command may be as follows:

> sudo apt-get install python3

pip

The pip program should be installed so some needed packages can be easily installed.

On Ubuntu, the command may be as follows:

> sudo apt-get install python3-pip

graphviz

The graphviz program should be installed so doxygen can create dependency graphs.

On Ubuntu, the command may be as follows:

> sudo apt-get install graphviz

Sphinx

The Sphinx Python Documentation Generator is used to generate all YumaPro documentation. The Sphinx Read The Docs theme sphinx-rtd-theme is used for the documentation set.

> sudo pip3 install -U sphinx sphinx-rtd-theme

Breathe

The Breathe is used to integrate Doxygen XML information into the Sphinx documentation.

> sudo pip3 install -U breathe

make

The GNU Make program is used to invoke the 'doxygen' and 'sphinx-build' programs.

> sudo apt-get install make

Build the HTML Files

The YumaPro documentation root is the netconf/doc directory. The top-level directory will be called 'yumapro'.

> cd yumapro/netconf/doc
> make clean
> make newdoc

This may take a long time depending on the computer used.

Access the Output Files

Doxygen Output

Fist doxygen will run and generate HTML and XML output files.

  • yumapro/netconf/doc/doxygen/output/html

    • The Doxygen WEB pages are in this directory

    • This entire directory can be used as a standalone WEB site.

    • No other files from the build tree should be needed or accessed from the 'html' directory.

  • yumapro/netconf/doc/doxygen/output/xml

    • Doxygen also produces a large number of XML files in this directory.

    • These files are used by the 'Breathe' program to extract documentation from the source code H files.

    • This directory does not need to be installed on the doxygen or sphinx WEB site.

The local version built on disk can be accessed with the 'index.html' front page. For example, a 'file' URL to access the Doxygen output might look like:

file:///home/andy/swdev/ypwork/netconf/doc/doxygen/output/html/index.html

Sphinx Output

The 'sphinx-build' command should create a 'build' directory that should have 2 sub-directories:

  • yumapro/netconf/doc/sphinx/build/doctrees

    • This is an internal directory needed by sphinx. It is not needed on the target WEB site.

  • yumapro/netconf/doc/sphinx/build/html

    • This entire directory can be used as a standalone WEB site.

    • No other files from the build tree should be needed or accessed from the 'html' directory.

The local version built on disk can be accessed with the 'index.html' front page. For example, a 'file' URL to access the Sphinx output might look like:

file:///home/andy/swdev/ypwork/netconf/doc/sphinx/build/html/index.html