Document a codebase
===================

A public name needs a contract. Explain its input, its result, its ownership,
and the conditions under which it fails. A signature alone is not a manual.

Odin
----

.. code-block:: toml

   odin_autoapi_dirs = ["../../lib"]
   odin_autoapi_root = "api"
   odin_autoapi_options = ["members", "undoc-members"]

Guidedog reads Odin source through Odin's parser.
It does not compile or run the documented package.
The generated pages join the document graph and object inventory.
The repository's separate API project is ``docs/api``.
See :doc:`../odin` for directives, signatures, and options.

Python
------

.. code-block:: toml

   extensions = ["sphinx.ext.autodoc"]
   autodoc_source_paths = ["../src"]

Guidedog parses Python source rather than importing it.
This avoids import side effects. It also means runtime-generated objects may be absent.
Describe those objects explicitly when they are part of the public interface.
See :doc:`../autodoc` for the exact discovery rules.

Link across projects
--------------------

Publish the generated ``objects.inv`` with the site.
An intersphinx mapping can then resolve names from another project.
Use explicit mappings for reproducible builds.
See :doc:`../intersphinx`.