18. Documentation¶

This documentation is a Sphinx project in docs/. It is published to Read the Docs, served by every C-PAT deployment at /docs, and built as part of every release. This page explains how to build it, where things live, and the conventions the pages follow.

18.1. Where the documentation lives and how it is published¶

The sources are reStructuredText files under docs/source/, one folder per section, plus docs/index.rst as the root.
Read the Docs builds the main branch and publishes it at https://c-pat.readthedocs.io/en/main/. The build configuration is .readthedocs.yaml at the repository root: Ubuntu 22.04, Python 3.12, and docs/requirements.txt.
The release workflow builds the documentation in a container immediately before it builds the application image, and the Dockerfile copies docs/_build/html into the image. The API serves that directory at /docs. Every deployment therefore carries the documentation that matches its version, and a change to these pages reaches deployed users with the next release. See Release process.
docs/index.html redirects to _build/html/index.html for browsing a local build without a server.

18.2. Build the documentation¶

The build runs in a container so that nobody needs a local Python installation. The image is built from docs/Dockerfile and installs the hash-locked package versions in docs/requirements.txt. See Dependencies and upgrades for how that file is regenerated.

cd docs
docker build -t sphinx-w-requirements .
docker run --rm -v "${PWD}:/docs" sphinx-w-requirements make html

cd docs
./build.sh

build.sh and make.bat wrap the same two commands and clean _build first. The output is in docs/_build/html; open index.html there. Both scripts also accept outdated, which lists the documentation packages with a newer release; see Dependencies and upgrades.

Warning

On Windows, run the Docker commands from PowerShell. Git Bash rewrites the /docs volume path, the container sees an empty directory, and Sphinx stops with config directory doesn't contain a conf.py file (/docs). If you must use Git Bash, set MSYS_NO_PATHCONV=1 first.

To build with a local Python instead, create a virtual environment with Python 3.12 or newer, install the requirements, and run Sphinx directly:

cd docs
python -m venv .venv
.venv\Scripts\pip install --require-hashes --only-binary :all: -r requirements.txt
.venv\Scripts\sphinx-build -W --keep-going -b html . _build/html

cd docs
python -m venv .venv
.venv/bin/pip install --require-hashes --only-binary :all: -r requirements.txt
.venv/bin/sphinx-build -W --keep-going -b html . _build/html

The -W flag turns warnings into errors and --keep-going reports all of them. The PR Tests workflow builds with those flags whenever a pull request changes files under docs/, so a warning that passes locally still fails the check. The current tree builds without warnings; keep it that way.

To check external links, run the linkcheck builder the same way and read _build/linkcheck/output.txt.

18.3. Structure¶

The root docs/index.rst lists four sections, each a folder under docs/source/ with its own index.rst:

Section	Content
`install/`	Setup and Deployment: installation, authentication, database, logging, reverse proxy, environment variables, securing, integrations.
`admin/`	Administrative Guide: the Admin Portal.
`user/`	User Guide: POAM creation, management, export, integrations, assets, labels.
`developer/`	This guide.

Every section index has the same shape: a label .. _<section>-index:, a .. meta:: description, an introductory sentence, and a toctree with :maxdepth: 2, :numbered: 4, and :caption: Contents:. The numbering is why pages have no numbers in their titles.

Images live under docs/assets/images/, with a subfolder per section for new material (docs/assets/images/developer/ holds the diagrams in this guide). Static files for the theme are under docs/_static/. The Sphinx configuration is docs/conf.py; the release workflow rewrites its version and release values, so do not edit those by hand.

18.4. Page conventions¶

Follow the existing pages. The rules below are the ones that matter for consistency.

Label first. Line 1 of every page is .. _<label>:. Pages in this guide use developer-<file-name>. Cross-reference with :ref: and never with a file path, so that pages can move.
Headings. The title is underlined with #; the next levels use =, -, ~, and ^ in that order. Use underlines only. Write headings in sentence case, and start task headings with a verb.
Admonitions. note for context the reader might miss, warning for anything that loses data, breaks a deployment, or exposes a secret, tip for a shortcut. One admonition per screen of text is enough.
Tables. Use list-table with :widths: and :header-rows: 1. Existing tables also carry :class: tight-table, which the previous theme needed to stop cell text being forced onto a single line; the current theme wraps cells, so the class does nothing and new tables do not need it. Variable references use csv-table from a .csv file next to the page, as install/environment-variables.rst does.
Code. Every code-block names a language. Introduce every block with a sentence. When a command differs between Windows and Linux, use the tabs directive with code-tab:: powershell and code-tab:: bash.
Images. Use the thumbnail directive with a :title: so the image opens in the lightbox. Prefer SVG, and follow the pattern the diagrams in this guide use: the light values sit in the presentation attributes, and a @media screen and (prefers-color-scheme: dark) block inside the file flips them for a reader whose system is dark. The block has to live in the file because an SVG referenced with <img> cannot be reached by the page stylesheet, and the light set has to be the one in the attributes so the diagram prints correctly. Take the colours from docs/_static/css/00-tokens.css, leave the canvas transparent so the page shows through, and do not depend on a script or a font from the network: the documentation is read offline inside deployments.
Glossary. Link a term with :term: on its first use in a page; the entries are in Glossary.
Line endings and wrapping. Files use one paragraph per line, as the existing pages do.

The theme is furo, restyled to match the C-PAT client in four layers. docs/_static/css/00-tokens.css holds the primitives copied from the client – the surface ramp, the severity colours, and the geometry and motion constants – and is the only file allowed to contain a colour literal. docs/conf.py maps those primitives onto furo’s own light_css_variables and dark_css_variables, so every light-or-dark decision is made in one place. docs/_static/css/10-constructs.css styles the page constructs and reads only var(). docs/_static/css/20-print.css is registered with media="print" and is written for a browser printing with background graphics switched off, which is the default: contrast there has to come from text colour and borders, never from a background. docs/_templates/page.html restores the breadcrumbs and the pager above the article. When you introduce a directive the site has not used before, build it, look at it in both colour schemes, and print it.

18.5. Writing style¶

The pages follow the Google developer documentation style in the points that matter most:

Address the reader as “you”. Use the active voice and the present tense.
Say what the software does, not what it “should” do, unless you are stating a rule for contributors.
Put file names, commands, variables, paths, and values in code font.
Make link text say where the link goes.
Use numbered lists only for steps that happen in order.
Keep each page to one kind of content: a tutorial that teaches, a how-to that lists steps for a task, a reference that lists facts, or an explanation that discusses how and why. When a topic needs both an explanation and steps, write two pages and link them, as Database and migrations and Add a database migration do.

State volatile numbers (counts, versions, limits) with the version they were true for, or point at the file that holds them. Stable rules can be stated outright.

18.6. Documentation in a pull request¶

A pull request that changes behaviour updates the documentation in the same change. As a guide:

A visible feature changes the User Guide or the Administrative Guide.
A new environment variable is added to docs/source/install/envvars.csv and to the page that describes its subject. See Add a configuration variable.
A change to how the code is organized, built, tested, or released changes this guide.
A change to the API contract that adds a convention changes API contract and reference.

The PR Tests workflow builds the documentation with -W when files under docs/ change. A build failure in that job means a broken reference, a malformed directive, or a missing file; the log names the file and line.