Maintain this documentation¶
There are three Guidedog projects: docs/manual, docs/api, and docs/gds.
The manual and GDS began with guidedog quickstart. Edit their generated templates in place.
Do not place design records in the manual’s table of contents.
Build the manual¶
From the repository root:
build/guidedog build html docs/manual -j auto -W
build/guidedog build pdf docs/manual -W
build/guidedog serve docs/manual
The manual includes the complete Odin API reference in its table of contents.
The PDF command creates one book, with links between explanations and declarations.
Both the manual and the separate API project generate their reference from lib/.
There is no copied API manuscript to keep in sync.
To build the API project on its own:
build/guidedog build html docs/api -W
build/guidedog build pdf docs/api -W
Build and check discussions¶
build/guidedog gds index
build/guidedog gds check
build/guidedog gds build --target=both
The GDS CLI manages metadata, numbers, state, and recovery.
Its RST publication path calls the project engine.
It produces a complete HTML site and a separate PDF for each record.
A selector limits the PDFs. HTML remains a coherent site with a complete catalog.
A selected PDF preview uses _build/selected/<artifact>/pdf.
It leaves the complete catalog in _build/pdf intact.
build/guidedog gds build guidedoc-odin --target=pdf
build/guidedog build html docs/gds -W
build/guidedog build pdf docs/gds -W
The ordinary project commands work too.
The GDS project uses its own conf.toml and its own _build directory.
Read docs/gds/workflow.rst for the authoring workflow.
Before publishing¶
Check links and diagnostics. Inspect wide tables and code blocks. Render the PDF pages after changing typography. Test the HTML at desktop and phone widths, in light and dark modes. Make sure the mathematics and diagrams work without a network connection. For engine changes, run the relevant library and integration tests.