Build and preview¶

The starter pack provides make commands to build and view the documentation. All these commands will automatically set up the Python environment if it isn’t set up yet.

Build the documentation¶

To build the documentation, run the following command:

make html

This command installs the required tools and renders the output to the _build/ directory in your documentation directory.

Important

When you run make html again, it updates the documentation for changed files only.

This speeds up the build, but it can cause you to miss warnings or errors that were displayed before. To force a clean build, see Run a clean build.

Make sure that the documentation builds without any warnings (warnings are treated as errors).

Run a clean build¶

To delete all existing output files and build all files again, run the following command:

make clean-doc html

To delete both the existing output files and the Python environment and build the full documentation again, run the following command:

make clean html

View the documentation¶

To view the documentation output, run the following command:

make serve

This command builds the documentation and serves it on http://127.0.0.1:8000/.

Live view¶

Instead of building the documentation for each change and then serving it, you can run a live preview of the documentation:

make run

This command builds the documentation and serves it on http://127.0.0.1:8000/. When you change a documentation file and save it, the documentation will be automatically rebuilt and refreshed in the browser.

Important

The run target is very convenient while working on documentation updates.

However, it is quite error-prone because it displays warnings or errors only when they occur. If you save other files later, you might miss these messages.

Therefore, you should always Run a clean build before finalising your changes.

Build a PDF¶

Build a PDF locally with the following command:

make pdf

PDF generation requires specific software packages. If these files are not found, a prompt will be presented and the generation will stop.

Required software packages include:

dvipng
fonts-freefont-otf
latexmk
plantuml
tex-gyre
texlive-font-utils
texlive-fonts-recommended
texlive-lang-cjk
texlive-latex-extra
texlive-latex-recommended
texlive-xetex
xindy

On Linux, required packages can be installed with:

make pdf-prep-force

Note

When generating a PDF, the index page is considered a ‘foreword’ and will not be labelled with a chapter.

Important

When generating a PDF, it is important to not use additional headings before a toctree. Documents referenced by the toctree will be nested under any provided headings.

A rubric directive can be combined with the h2 class to provide a heading-styled rubric in the HTML output. See the default index.rst for an example. Rubric-based headings aren’t included as entries in the table of contents or the navigation sidebar.