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 one version of the documentation maintained starting in December 2022.

  • Only the latest release train contains up to date documentation.

  • Currently the 22.10T release train must be used to build the documentation.

About YumaPro 'newdoc'

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.

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

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

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 at-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

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

The Doxygen WEB pages are in the yumapro/netconf/doc/output/html directory generated by 'make newdoc'.

  • 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 Doxygen output might look like:

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

Doxygen also produces a large number of XML files in the 'output/xml' directory. These files are used by the 'Breathe' program to extract documentation from the source code H files.

Sphinx Output

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

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

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

The 'doctrees' directory is used internally by sphinx. It is not needed on the target WEB site.

The Sphinx WEB pages are in the yumapro/netconf/doc/sphinx/build/html directory generated by 'make newdoc'.

  • 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