.. _usage_yclept_makedoc:

``yclept make-doc``
========================

The command-line tool `yclept make-doc` allows you to generate an RST-style document tree from your base configuration file.  For example, if you have a base configuration file called `base.yaml` and your package is structured like this:

.. code-block:: text

   rootdir
   ├── mypackage/
   │   ├── config.py
   │   ├── data/
   │   │   ├── base.yaml
   │   │   └── __init__.py
   │   ├── docs/
   │   │   └── source/
   │   │       └── intro.rst
   │   ├── __init__.py
   │   └── otherstuff/
   │       └── stuff.py
   ├── README.md
   └── setup.py

To use ``yclept make-doc``, you would first change to the ``docs/source`` directory and then run the command:

.. code-block:: console

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

This will generate a header file ``config_ref.rst`` and a document tree rooted in ``docs/source/config_ref/``.  To see an example of this, visit `pestifer's documentation <https://pestifer.readthedocs.io/en/latest/>`_, and specifically the `configuration file reference <https://pestifer.readthedocs.io/en/latest/config_ref.html>`_.  Every thing under that link was generated by ``yclept make-doc``.

Each ``rst`` file geneerated by ``yclept make-doc`` has a footer that is generated from the ``footer-style`` argument.  The default footer style is called "paragraph", and appears in the RST file as:

.. code-block:: rst

   ----

   *This file was automatically generated by **ycleptic** v1.6.0 on 18-06-2025.*

Availabe footer styles are ``note``, ``paragraph``, ``rubric``, or ``comment``.  A ``comment`` footer will be included as an RST comment and will therefore not be visible in the rendered document. 
