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¶
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 Documenting Odin for directives, signatures, and options.
Python¶
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 Documenting Python with 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 Linking to other projects.