Process RST Documentation

Normalize headings, simple paragraphs, and C++ links in RST files. A normal invocation performs cleanup only; demo execution requires an explicit --demos selection.

./erbsland-core-tool doc-process-rst doc/development --recursive

Use --dry-run to preview changes and --check to fail if normalization is required, without writing documents. Cleanup requires the Doxygen XML index, refreshed by doc-build after source API changes.

Demo Processing

--demos sync updates stale excerpts and captures. --demos validate checks synchronization without publishing generated demo changes. --demos refresh recursively regenerates all blocks, and --demos migrate converts legacy metadata only. --no-cleanup selects demo-only operation, and --force regenerates blocks despite matching hashes. Explicit demo processing may execute demos during preview and check modes.

Demo updates happen before cleanup, with one final document write. Build selected demo executables first; capture works on macOS, Linux, and Windows and is bounded by time and output limits. The Demo Executable Root configuration setting defaults to cmake-build-debug/demo-apps on every platform. Set a project-relative or absolute directory for a special build. Review modified source excerpts, expected failures, fixture use, and terminal output.

Source Presentation

Use the Demo Text Replacement section list to simplify generated source excerpts without changing compiled demos. Each entry has a regular-expression Pattern and a Replacement using Core capture references. Rules run in declaration order, after :show: and :hide: select the source. For example, this configuration presents the demo capture helper as the public application API:

*[ Doc Process Rst . Demo Text Replacement ]
Pattern: /(?:demo::)?DemoTerminal::enable\((?<application>[A-Za-z_]\w*)\);/
Replacement: "{application}.enableTerminal();"

The repository configuration also handles DemoTerminal::enable(*this). Replacement rules are excluded from demo fingerprints. After changing a rule, manually review the affected excerpts and use --demos sync --force on those pages to refresh them.

See Run and Configure Commands for shared invocation options and Documentation Maintenance Reference for the technical contracts.