tutorial.md

Build your first diagram

This tutorial builds a small Sphinx site with a publishing flowchart, then adds a caption and zoom controls. You need Python 3.11 or newer, pip, Git, Node.js 22+, and pnpm 11.11.0. This tutorial installs the development version from the repository.

Create a project

In an empty working directory, create a virtual environment and install the extension:

python -m venv .venv
. .venv/bin/activate
python -m pip install "sphinx-pele @ git+https://github.com/python-project-templates/sphinx-pele.git@main"
mkdir docs

On Windows, use .venv\Scripts\activate to activate the environment.

Create docs/conf.py:

project = "Publishing guide"
extensions = ["sphinx_pele"]
root_doc = "index"

Create docs/index.rst:

Publishing guide
================

.. mermaid::

   flowchart LR
       Draft --> Review --> Published

Build and view it

Run:

python -m sphinx -W -b html docs docs/_build/html
python -m http.server 8000 --directory docs/_build/html

Open http://localhost:8000/. The page should show three nodes labeled Draft, Review, and Published, joined from left to right on a wide screen. Keep the server running while you edit; use a second terminal for the next build.

Add a caption and controls

Replace the directive in docs/index.rst with:

.. mermaid::
   :caption: Publishing flow
   :name: publishing-flow
   :alt: A draft is reviewed before publication.
   :zoom: true

   flowchart LR
       Draft --> Review --> Published

See :ref:`publishing-flow`.

Build again, then reload the browser:

python -m sphinx -W -b html docs docs/_build/html

The diagram now has a caption, a link to the figure, and zoom buttons. Click the zoom-in button, then reset the view. Resize the browser to see the diagram adapt to the page width.

Change the font size

Add this line to docs/conf.py:

pele_options = {"fontSize": 20}

Rebuild and reload once more. Diagram labels should be larger; the caption keeps the Sphinx theme's text style.

Your site now contains a rendered diagram with a caption and reader controls. Continue with Markdown and file-based diagrams, or copy a different diagram from the gallery.