Building the Documentation

All documentation and related files are located in the source tree under the doc directory. The Makefiles must be generated by the main configure script. The current configure script switch for enabling documentation builds is --enable-docs.

Additional packages required for building the documentation.

System installs

These should be installed via yum or dnf.

graphviz

Graph visualization, used for diagrams in many places.

java

A java based utility is run to generate diagrams and so a java executor is required.

python2-pip

PIP for installing Python packages. Install this if you are using Python 2.

python3-pip

PIP for installing Python packages. Install this if you are using Python 3.

PIP installs

These should be installed using pip.

sphinx

A Python package that is the based Sphinx Documentation.

sphinx-rtd-theme

Style package for the preferred ATS documentation style.

sphinxcontrib-plantuml

Support for using plantuml inline.

sphinx-intl

International support, which is needed if a non-English version is built. Currently a Japanese (JA) version is available.

These should be also installed using pipenv and doc/Pipfile. To setup the environment, run below commands from within the doc/ directory of the Traffic Server source tree:

pipenv install
pipenv shell

With a configured source tree, building the documentation requires only the invocation make html from within doc/. For repeated builds while working on the documentation doing make html again is sufficient. After fixing all warnings / errors, however, it is advisable to clean out the built and intermediate files by running the following instead (again, from within the doc/ directory of the Traffic Server source tree):

make clean && make html

This will ensure that make doesn’t inadvertently skip the regeneration of any targets.

Note

It is expected that any PR updating the documentation builds without any errors or warnings. This can be easy to miss if the full build is not done before submitting the pull request.

To view the built documentation, you may point any browser to the directory doc/docbuild/html/. If you are building the documentation on your local machine, you may access the HTML documentation files directly without the need for a full-fledged web server, as all necessary resources (CSS, Javascript, and images) are referenced using relative paths and there are no server-side scripts necessary to render the documentation.