How a project works¶
The project root is the directory containing conf.toml.
root_doc names the document that starts the reading order.
Guidedog discovers source documents, reads them, resolves their relations,
and publishes a complete output generation.
Documents and resources¶
A source suffix selects a reader. RST and project Markdown share the project graph.
Images and downloads are resources. Guidedog copies resources that the documents use.
Theme assets are listed in html_static_path.
An include must remain within the source directory or the configured include_roots.
Separate projects¶
Keep a manual and design records in separate projects.
They have different readers and different reading orders.
Each project has its own configuration, templates, cache, and output.
The Guidedog repository uses docs/manual and docs/gds this way.
Incremental work¶
Guidedog records the inputs and lookups used by each output. A changed source is reread. A changed dependency invalidates its users. A changed template can affect every page. An unchanged document may be loaded from its saved object.
The cache is evidence about a previous build. It is not the source of truth.
-E discards the saved environment for the next build.
-a writes all outputs. They solve different problems.
An explicit timestamp in a template is also an input to the rendered page.
A page that prints the current minute can change even when its prose does not.
Use SOURCE_DATE_EPOCH when you need a fixed build time.
Publication¶
A build writes changes to a sibling staging directory. It completes that directory, flushes the files and records, and then switches generations. Readers see a complete previous or new publication. An interrupted commit is settled on the next build. The design and its proof obligations are in Publish one complete generation.