Building this manual

Dependencies

Use Python 3 with Sphinx, the Read the Docs theme and Breathe, and Doxygen. In an MSYS2 UCRT64 shell:

pacman -S --needed mingw-w64-ucrt-x86_64-doxygen \
    mingw-w64-ucrt-x86_64-python-sphinx \
    mingw-w64-ucrt-x86_64-python-sphinx_rtd_theme \
    mingw-w64-ucrt-x86_64-python-breathe

Graphviz is optional and is not used by this manual. No compiler, Tk display, installed RBC package, or Cairo library is needed for extraction.

Targets

After configuring RBC:

make doc-dev
make check-doc-dev

Both publish HTML in docs/developer/html in the source tree, including when invoked from an out-of-tree build. This is available to GitHub Pages when it publishes the repository’s docs directory. The check target also fails on Doxygen or Sphinx warnings. Neither depends on binaries or changes the existing make doc pipeline. make clean removes the default developer documentation build directory.

These commands also work without configuring:

tclsh docs/developer/build.tcl
tclsh docs/developer/build.tcl --strict --build-dir "_build/developer"

From a Visual Studio developer prompt in win, the corresponding targets are nmake -f makefile.vc doc-dev and check-doc-dev. That makefile still requires its normal Tcl/Tk build setup.

Override DOC_DEV_PYTHON, DOXYGEN, DOC_DEV_BUILD or DOC_DEV_HTML to select executable paths and output location:

make check-doc-dev DOC_DEV_PYTHON=/ucrt64/bin/python DOXYGEN=/ucrt64/bin/doxygen

The runner uses only Tcl core commands. Python remains required by Sphinx and Breathe, and for Sphinx’s small conf.py configuration. The runner invokes Sphinx through the executable selected by --python (default: python); install Breathe, Sphinx and sphinx-rtd-theme for that interpreter. Do not mix MSYS, UCRT64 and a separate Windows Python installation accidentally. Paths containing spaces are supported. Each executable override names one executable, not a command with extra flags.

Generated files and validation

Maintained sources live in docs/developer. Doxygen configuration, XML, warning logs and Sphinx caches live under the build directory. HTML is published separately under docs/developer/html. Commit that directory to publish the manual with GitHub Pages. The published pages, assets and .nojekyll are retained by make clean. With the default paths, clean removes the entire source and build root _build directories, the developer source’s Python bytecode cache, and Sphinx’s .doctrees, _sources and .buildinfo from the developer HTML directory. Use --html-dir PATH for a different HTML destination. XML is regenerated and all pages rebuilt on each invocation.

Doxyfile.in explicitly lists the two renderer headers and the common graph header/source pair, the public/private vector headers, and the binding header/source pair. Extraction does not follow includes into Tk or SDK headers. Reference pages select maintained contracts; undocumented functions are not a coverage target yet. Platform and Cairo backend implementations are not combined into misleading duplicate entries. Future chapters must select inputs deliberately.

Static graph callbacks belong to a Doxygen group, so Breathe can render them without globally enabling implementation-file lookup (which can duplicate header declarations on older Breathe versions). The Doxygen preprocessor removes only the legacy register qualifier for Sphinx’s C signature parser; the C source and compiler input are unchanged.

Strict checking validates included comments and references, not whole-project coverage. Undocumented-member warnings are disabled during this incremental migration; EXTRACT_ALL remains disabled. Extend the input list and reference pages as each module is documented.

Developer HTML is not yet installed or included in binary distribution archives. Existing user documentation installation is unchanged.

Windows backend extraction runs as a second Doxygen project using the same settings template but a Windows-only source input. Its XML and warnings are stored in doxygen-win/xml and doxygen-win-warnings.log below the build directory. Breathe selects this project explicitly for the Windows reference. Both extraction passes run on either build host; neither compiles code or requires Windows SDK headers. Separate projects prevent identical X11/Windows function names and private structure layouts from being merged. Strict mode checks both warning logs and restores both XML environment variables on exit.

Doxygen callback declaration compatibility

Some Doxygen versions place a function-pointer member’s closing parenthesis in its XML type instead of its argument string. Breathe then emits invalid C such as void(*) text (...). The Tcl build driver normalizes that generated XML before Sphinx runs, producing void (*text)(...) while retaining member contracts and link targets. Source declarations and already-compatible XML are unchanged; no warning suppression or dependency upgrade is required.

The helper’s regression checks run without Tk, RBC or documentation tools:

tclsh tests/build/build.doxygenCompat.test

Theme and publishing

Both manuals use sphinx_rtd_theme with expandable navigation and RTD’s default content width. Shared styles live in docs/theme/rbc.css and docs/theme/rbc-layout.css. Edit these sources, not the generated _static copies. Tables wrap within the content column; field lists use bounded columns and stack labels above descriptions on narrow screens. These rules do not change C declaration signature layout. Images retain their natural sizes unless they need to shrink to fit, and expandable examples retain their highlighted controls.

The developer-only docs/theme/rbc-developer.css also bounds deep sidebar indentation and wraps long C identifiers.

Both builders copy the maintained stylesheets before Sphinx computes asset hashes and verify the resulting copies. Missing sources or mismatched output copies fail the build rather than publishing stale styles.

Keep docs/.nojekyll at the GitHub Pages publishing root. The developer build also emits docs/developer/html/.nojekyll so its output can be hosted independently. Publish each complete HTML output tree, including _static CSS, JavaScript and fonts. The theme requires no Read the Docs hosting service. Existing page names and C reference targets are unchanged by the theme.

After a full MSYS2 update (pacman -Syu), verify the selected interpreter:

python -m sphinx --version
python -c "import sphinx_rtd_theme, breathe; print(sphinx_rtd_theme.__file__)"

Use UCRT64 packages together; do not install the theme into a different Python from the one selected by DOC_DEV_PYTHON. For non-MSYS2 environments, install sphinx, breathe and sphinx-rtd-theme into the Python environment used by the documentation builder.