This directory contains the source code for Traffic Server documentation.
Traffic Server documentation is built using the Sphinx documentation generator. The Sphinx build tool is distributed as a Python package. A Pipfile is provided to conveniently configure a Python virtual environment with the needed Sphinx packages.
In addition to the Sphinx Python package requirements, building the documentation will also require Java and graphviz system packages to be installed.
Building the docs requires passing -DENABLE_DOCS=ON to cmake (docs generation is off by default), and then using the appropriate build target. The build steps will automatically install a Pipenv virtual environment using docs/Pipfile and do what is necessary to build the docs.
cmake -B docs-build -DENABLE_DOCS=ON cmake --build docs-build --target generate_docs
The generated HTML docs will be in docs-build/doc/docbuild/html.
# Letter paper size (US standard) cmake --build docs-build --target generate_pdf # A4 paper size (International standard) cmake --build docs-build --target generate_pdf_a4
The generated PDF will be in docs-build/doc/docbuild/latex/ApacheTrafficServer.pdf (or docs-build/doc/docbuild/latex-a4/ for A4 format).
Once the build completes, you can use Python's http.server module to create a local test HTTP server to view the built documentation. Note: http.server is only designed for test purposes, not for production use.
cd docs-build/doc/docbuild/html python3 -m http.server 8888 Serving HTTP on 0.0.0.0 port 8888 (http://0.0.0.0:8888/) ...
You can then view the rendered HTML using your browser of choice and navigating to the http://0.0.0.0:8888/ URL.