yclept make-doc

The yclept make-doc command generates a Sphinx RST document tree from your base configuration file.

Basic usage

Given a package structured like this:

myproject/
├── mypackage/
│   ├── data/
│   │   ├── base.yaml
│   │   └── __init__.py
│   └── __init__.py
├── docs/
│   └── source/
│       └── intro.rst
└── pyproject.toml

Run yclept make-doc from the project root, passing the full path to both the base config file and the desired output location:

$ yclept make-doc mypackage/data/base.yaml --root docs/source/config_ref

This writes docs/source/config_ref.rst and populates docs/source/config_ref/ with one RST file per attribute, mirroring the nesting of your base config. No cd into docs/source is required.

Then add config_ref to your Sphinx toctree:

.. toctree::
   :maxdepth: 1

   config_ref

For a live example of the output, see pestifer’s configuration reference, which is generated entirely by yclept make-doc.

ReadTheDocs integration

To regenerate the doc tree on every RTD build, add the command to the pre_build jobs in .readthedocs.yaml:

build:
  os: ubuntu-24.04
  tools:
    python: "3.12"
  jobs:
    pre_build:
      - yclept make-doc mypackage/data/base.yaml --root docs/source/config_ref --footer-style raw-html