Building the Documentation

The CPACS documentation is generated by cpacs-doc, which reads the documentation out of schema/cpacs_schema.xsd and the figure catalogue out of documentation/media.json. The generator lives in its own repository; this repository holds only its input.

The same generator is run by the Build documentation workflow, which deploys the site to https://dlr-sl.github.io/CPACS/ on every push to develop.

---

Step 1: Install uv

The generator is a Python project managed with uv, which provides both the Python version and the dependencies. Install it once:

winget install --id=astral-sh.uv -e

On Linux or macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

The generator's README describes two alternatives (pip in a virtual environment, or conda) for anyone who would rather not add uv.

---

Step 2: Check Out the Generator

Clone it next to this repository, or into the ignored .cpacs-doc/ directory inside it:

git clone https://github.com/DLR-SL/cpacs-doc.git .cpacs-doc
uv sync --locked --project .cpacs-doc

uv sync --locked installs the versions the generator was tested against. Repeat it after pulling changes into .cpacs-doc.

---

Step 3: Build the Documentation

From the root of this repository:

uv run --project .cpacs-doc cpacs-doc build schema/cpacs_schema.xsd --site -o build/doc

This writes the static site to build/doc, which any web server can serve. Two further options are available:

• --single additionally writes build/doc/cpacs-doc.html, the whole documentation as one self-contained file with the figures embedded. It is roughly 20 MB and opens from disk without a server.

• report instead of build writes only the build report — undocumented types, unknown vocabulary, unresolvable figure references — and writes no files:

  uv run --project .cpacs-doc cpacs-doc report schema/cpacs_schema.xsd
  

The command exits with status 1 when the report holds errors, which is what makes the workflow fail on a broken schema. Warnings and notes do not fail the build.

---

Working on the Documentation Text

While editing the xsd:documentation in the schema, serve rebuilds on every save and serves the viewer at http://127.0.0.1:8000:

uv run --project .cpacs-doc cpacs-doc serve schema/cpacs_schema.xsd

The wording conventions the documentation text follows, and the form of the XML examples in it, are described in the development guidelines.

---

Figures

documentation/media.json maps the image ids used in the schema documentation to the files under documentation/figures/ and documentation/equations/. A figure referenced from the schema but missing from the catalogue is reported, as is a catalogue entry no documentation references. The catalogue is found automatically because it sits in documentation/ next to the schema/ directory.

---

Tool-Specific Documentation

Generating documentation for a tool-specific schema (schema/toolspecific_template.xsd) is not yet supported by the new generator. The Sandcastle project that used to build it has been removed together with the rest of the Sandcastle build.