CongoCC Documentation

This repository holds the source for the CongoCC documentation. The pages are written in reStructuredText and built with Sphinx; the published site is hosted on Read the Docs.

This README is for contributors editing the documentation locally. It walks through setting up a build environment and previewing your changes live in a browser as you edit.

Repository layout

source/                 Sphinx sources
├── conf.py             Sphinx configuration
├── index.rst           top-level landing page (the three guides)
└── docs/
    ├── reference/      Reference Manual
    ├── userguide/      User Guide
    └── targets/        Target Language Guide
build/                  generated output (not tracked in git)
tools/                  maintenance tools (e.g. settings-extractor)

The three guides are wired together through toctree directives: every page is listed in the landing page of its section (for example source/docs/reference/reference.rst). When you add a page, add it to the nearest toctree or Sphinx will warn that the document is not included.

Prerequisites

• Git
• Python 3.14 — the version is pinned in .python-version
• uv — used to manage Python and the virtual environment

Set up a build environment

1. Install uv

uv is a single self-contained binary. Install it with the official installer:

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

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

(Alternatively, brew install uv or pipx install uv.)

2. Install Python 3.14

Let uv install the pinned interpreter:

uv python install 3.14

3. Clone the repository

git clone https://github.com/richcar58/congocc-docs.git
cd congocc-docs

4. Create and activate a virtual environment

uv venv creates a .venv using the pinned Python from .python-version:

uv venv

# Activate it:
source .venv/bin/activate        # macOS / Linux
# .venv\Scripts\activate         # Windows (PowerShell/cmd)

5. Install Sphinx and sphinx-autobuild

Both are declared as dependencies, so installing them into the active environment is one command:

uv pip install sphinx sphinx-autobuild

(Equivalently, uv sync installs the exact, locked versions from pyproject.toml / uv.lock.)

Preview the docs live while editing

Run sphinx-autobuild to build the site, serve it, and rebuild automatically whenever you save a source file:

sphinx-autobuild source build/html

It prints a local URL — by default http://127.0.0.1:8000 — open it in a browser. Edit any .rst file under source/, save, and the page reloads on its own. Press Ctrl-C to stop the server. Add --open-browser to open the page automatically, or --port N to use a different port.

Tip: make livehtml runs the same command.

If you did not activate the virtual environment in step 4, prefix commands with uv run instead — for example uv run sphinx-autobuild source build/html.

Build the docs once

To produce the HTML without the live server:

make html
# or, equivalently:
uv run sphinx-build -M html source build

The output is written to build/html/; open build/html/index.html.

Editing conventions

• Keep the build warning-free. A broken cross-reference or a malformed table shows up as a Sphinx warning — treat warnings as errors.
• Because CongoCC has no numbered releases, mark a feature's availability with an ISO date using the standard directives, e.g. .. versionadded:: 2026-06-19 (these are configured to render as "Added 2026-06-19").
• The Settings Reference is kept in sync with the CongoCC source by the SettingsExtractor tool — see Maintenance tools below.

Maintenance tools

The tools/ directory holds small utilities for keeping the documentation accurate.

SettingsExtractor

tools/settings-extractor/SettingsExtractor.java keeps the Settings Reference (source/docs/reference/settings.rst) in sync with the CongoCC source. It reads the authoritative list of recognized settings from CongoCC's AppSettings.java and can diff it against the documentation, flagging any setting that is current in the source but missing from the docs (and listing documented names that are no longer settings).

It is a single-file Java program — no build step — and needs only a JDK 17+:

# Report any current setting that the docs do not cover
# (exits non-zero if any are missing — usable as a CI check):
java tools/settings-extractor/SettingsExtractor.java \
     /path/to/congocc/src/java/org/congocc/app/AppSettings.java \
     --diff source/docs/reference/settings.rst

See tools/settings-extractor/README.md for the other modes (a plain listing, a reStructuredText table export, and built-in self-tests).

Publishing

The site builds on Read the Docs from .readthedocs.yaml, which installs the locked dependencies with uv and runs sphinx-build. Merging to main triggers a rebuild of the published documentation.

Acknowledgments

Anthropic's Claude Opus 4.8 was used to generate the code and documentation in this project.