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:

.. code-block:: sh

   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:

.. code-block:: sh

   build/guidedog build html docs/api -W
   build/guidedog build pdf docs/api -W

Build and check discussions
---------------------------

.. code-block:: sh

   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.

.. code-block:: sh

   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.