Build and publish documentation
===============================

Build into the project's normal output directory:

.. code-block:: sh

   guidedog build html docs/manual -j auto -W
   guidedog build pdf docs/manual -W

The site is in ``docs/manual/_build/html``.
The PDF and its generated Typst source are in ``docs/manual/_build/pdf``.
A web server can serve the HTML directory as static files.
The site does not need an Odin server in production.

Choose an output directory
--------------------------

The Sphinx-style form takes the source and destination explicitly:

.. code-block:: sh

   guidedog build -b html docs/manual build/manual-site -W

Keep the output outside its sources. Guidedog refuses a layout where publishing
would replace the source tree. A custom destination has a stable sibling cache,
such as ``build/.manual-site.guidedog/.doctrees``.
The publication directory therefore contains only the publication.

Preview and check
-----------------

.. code-block:: sh

   guidedog serve docs/manual
   guidedog build dummy docs/manual -n -W

The dummy builder reads and resolves the project without making a publication.
Use it for a quick semantic check. It does not test the final page layout.

A reproducible time
-------------------

.. code-block:: sh

   SOURCE_DATE_EPOCH=1790812800 guidedog build html docs/manual -W

This pins the build time. Reproducibility also depends on sources, templates,
fonts, compiler versions, and resources. A fixed clock alone is not enough.

Publish the complete directory after the build succeeds.
A successful process exit is necessary; a visual check is still needed after template changes.