Maintaining this documentation
==============================

This chapter is for maintainers of MBDlyb-UI.

Building the documentation
--------------------------

The documentation uses `Sphinx <https://www.sphinx-doc.org/>`_ with the
Read the Docs theme. The sources are in ``docs/source``. Build the HTML
version with:

.. code-block:: sh

   uv run --group docs sphinx-build -b html docs/source docs/build/html

The Sphinx requirements are defined in the ``docs`` dependency group in
``pyproject.toml``. After ``uv sync --group docs`` and activating the
virtual environment, you can also run ``make html`` (or ``make.bat html`` on
Windows) in the ``docs`` folder. Open ``docs/build/html/index.html`` in a
browser, or publish the folder on any web server.

The repository contains a ``.readthedocs.yaml`` file, so the documentation
can be published on `Read the Docs <https://readthedocs.org/>`_ directly. Read
the Docs also builds PDF and zipped HTML versions.

Code reference
--------------

The *Developer reference* section is generated from the docstrings in
``src/mbdlyb_ui`` by `sphinx-autoapi <https://sphinx-autoapi.readthedocs.io/>`_.
AutoAPI reads the source code without importing it, so the code reference
can be built without ``mbdlyb``, NiceGUI or a database.

If a checkout of ``mbdlyb-base`` is next to this repository (the same
``../mbdlyb-base`` location used in ``pyproject.toml``), the reference also
includes the ``mbdlyb`` library, generated from ``../mbdlyb-base/src/mbdlyb``.
Otherwise this part is skipped. Read the Docs does not have that checkout,
so the published documentation contains only the MBDlyb-UI reference.

Write docstrings in
the Google style (``Args:``, ``Returns:``, ``Raises:``); the
``sphinx.ext.napoleon`` extension renders them. The build treats warnings as
errors, so give module-level functions unique names: a second definition with
the same name causes a "duplicate object description" warning.

Regenerating the screenshots
----------------------------

All screenshots and button icons are generated by
``docs/tools/capture_screenshots.py``. The script uses
`Playwright <https://playwright.dev/python/>`_ to drive a running instance of
the interface with the CDRadioPlayer example model. Regenerate them after
changes to the interface.

1. Load the CDRadioPlayer example into Neo4j
   (see :ref:`tutorial:1. Load the example`) and start the interface:

   .. code-block:: sh

      mbdlyb-ui --database cdradioplayer

2. Install the screenshot tools (the ``screenshots`` dependency group in
   ``pyproject.toml``) and the Chromium browser for Playwright:

   .. code-block:: sh

      uv sync --group screenshots
      uv run --group screenshots playwright install chromium

3. Run the script:

   .. code-block:: sh

      uv run --group screenshots python docs/tools/capture_screenshots.py --database cdradioplayer

   Use ``--url`` if the interface does not run at ``http://localhost:8080``.
   Use the Neo4j options (``--host``, ``--port``, ``--username``,
   ``--password``) as for ``mbdlyb-ui``. With ``--only`` you capture only some
   groups of screenshots, for example ``--only diagnoser dfd``.

The script does not change the model. It opens the edit forms without saving
them, and it cancels dialogs. It temporarily switches the global Editor/Tree
mode, and restores the original mode at the end. Do not run it while other
people use the same instance.

The images are written to ``docs/source/images/screenshots`` and
``docs/source/images/icons``.