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.

.. graphviz::
   :caption: The build separates discovery, meaning, presentation, and publication.
   :alt: Discover sources, read documents, resolve references, render artifacts, then publish.

   digraph build {
     graph [rankdir=TB, bgcolor="transparent", pad="0.3"];
     node [shape=box, style="rounded,filled", fillcolor="#edf5f2",
           color="#216553", fontname="Helvetica", fontcolor="#16382f"];
     edge [color="#216553"];
     discover [label="Discover\nsources + configuration"];
     read [label="Read\ndocuments + dependencies"];
     resolve [label="Resolve\ntoctrees + labels + objects"];
     render [label="Render\nHTML pages or PDF chapters"];
     publish [label="Publish\none complete generation"];
     discover -> read -> resolve -> render -> publish;
   }

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.

.. math::

   \text{reuse} = \text{same inputs} \land \text{same lookups} \land \text{output exists}

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 :doc:`../internals/publication`.