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
Additional packages required for building the documentation.
- System installs
Graph visualization, used for diagrams in many places.
A java based utility is run to generate diagrams and so a java executor is required.
PIP for installing Python packages. Install this if you are using Python 2.
PIP for installing Python packages. Install this if you are using Python 3.
- PIP installs
These should be installed using pip.
A Python package that is the based Sphinx Documentation.
Style package for the preferred ATS documentation style.
Support for using plantuml inline.
Internation support, which is needed if a non-English version is built. Currently a Japanese (
JA) version is available.
pipenv install pipenv shell
With a configured source tree, building the documentation requires only the
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
directory of the Traffic Server source tree):
make clean && make html
This will ensure that make doesn’t inadvertantly skip the regeneration of any targets.
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
images) are referenced using relative paths and there are no server-side scripts
necessary to render the documentation.