.. _usage_yclept_makedoc:

``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:

.. code-block:: text

   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:

.. code-block:: console

   $ 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``:

.. code-block:: rst

   .. toctree::
      :maxdepth: 1

      config_ref

For a live example of the output, see
`pestifer's configuration reference <https://pestifer.readthedocs.io/en/latest/config_ref.html>`_,
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``:

.. code-block:: 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

Footer styles
-------------

Each generated RST file ends with a footer whose appearance is controlled by
``--footer-style``.  The available styles are:

``paragraph`` (default)
   A horizontal rule followed by a plain paragraph.

   .. code-block:: rst

      ----

      This page was automatically generated by **ycleptic** v2.0.3 on 2025-09-04.

``comment``
   An RST comment — present in the source but invisible in the rendered output.

``note``
   A Sphinx ``.. note::`` directive.

``rubric``
   A ``.. rubric::`` heading outside the normal document hierarchy.

``raw-html``
   A ``.. raw:: html`` block, useful for styled footers with CSS classes.