Maintaining this documentation

This chapter is for maintainers of MBDlyb-UI.

Building the documentation

The documentation uses Sphinx with the Read the Docs theme. The sources are in docs/source. Build the HTML version with:

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 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. 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 to drive a running instance of the interface with the CDRadioPlayer example model. Regenerate them after changes to the interface.

Load the CDRadioPlayer example into Neo4j (see 1. Load the example) and start the interface:
```
mbdlyb-ui --database cdradioplayer
```
Install the screenshot tools (the screenshots dependency group in pyproject.toml) and the Chromium browser for Playwright:
```
uv sync --group screenshots
uv run --group screenshots playwright install chromium
```
Run the script:
```
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.