Merge pull request #5 from python-project-templates/tkp/documentation

Expand documentation and Mermaid examples

Author: timkpaine

.gitignore

@@ -161,4 +161,4 @@ AGENTS.md
 .github/hooks/sdlc.json
 .superpowers
 
-!docs/src/index.md
+!docs/index.md

Makefile

@@ -44,8 +44,8 @@ lint-js:  ## run js linter
 	cd js; pnpm lint
 
 lint-docs:  ## lint docs with mdformat and codespell
-	python -m mdformat --check README.md docs/src
-	python -m codespell_lib README.md docs/src
+	python -m mdformat --check README.md docs/index.md docs/src
+	python -m codespell_lib README.md docs/index.md docs/src
 
 lint: lint-js lint-py lint-docs  ## run project linters
 
@@ -61,8 +61,8 @@ fix-js:  ## fix js formatting
 	cd js; pnpm fix
 
 fix-docs:  ## autoformat docs with mdformat and codespell
-	python -m mdformat README.md docs/src
-	python -m codespell_lib --write README.md docs/src
+	python -m mdformat README.md docs/index.md docs/src
+	python -m codespell_lib --write README.md docs/index.md docs/src
 
 fix: fix-js fix-py fix-docs  ## run project autoformatters
 

README.md

@@ -9,10 +9,12 @@ Pele mermaid diagrams for Sphinx
 
 ## Usage
 
-Install and enable the extension:
+Install the development version from the repository, then enable the extension.
+Building from source requires Git, Node.js 22+, and pnpm 11.11.0 in addition to
+Python 3.11+:
 
 ```sh
-pip install sphinx-pele
+python -m pip install "sphinx-pele @ git+https://github.com/python-project-templates/sphinx-pele.git@main"
 ```
 
 ```python
@@ -31,9 +33,21 @@ pele_options = {"zoom": "auto"}
 MyST Markdown `mermaid` fences and external `.mmd` files also work. Replace
 `sphinxcontrib.mermaid` in `extensions` when migrating.
 
-See [usage](docs/src/usage.md), [configuration](docs/src/configuration.md), and
-[examples](docs/src/examples.md). HTML uses bundled Pele assets. Other builders
-retain Mermaid source.
+## Documentation
 
--> [!NOTE]
--> This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base).
+Start with the [first-diagram tutorial](docs/src/tutorial.md), or follow
+[how to add diagrams](docs/src/usage.md) in an existing Sphinx project.
+
+- [Styling and themes](docs/src/styling.md)
+- [Migration from sphinxcontrib-mermaid](docs/src/migration.md)
+- [Configuration reference](docs/src/configuration.md)
+- [Diagram gallery](docs/src/examples.md) and [reStructuredText examples](docs/src/rst-examples.rst)
+- [Troubleshooting](docs/src/troubleshooting.md)
+- [Rendering and non-HTML output](docs/src/rendering.md)
+- [Local development](docs/src/development.md)
+
+Build the documentation with `python -m sphinx -W -b html docs docs/_build/html`.
+See the [documentation homepage](docs/index.md) for the full navigation.
+
+> [!NOTE]
+> This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base).

docs/conf.py

@@ -4,7 +4,7 @@
 sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 extensions = ["myst_parser", "sphinx_pele"]
 project = "sphinx-pele"
-root_doc = "src/index"
-exclude_patterns = ["_build"]
+root_doc = "index"
+exclude_patterns = ["_build", "html"]
 html_theme = "alabaster"
 pele_options = {"zoom": False}

docs/index.md

@@ -0,0 +1,58 @@
+# sphinx-pele
+
+Render Mermaid diagrams in Sphinx with bundled Pele assets. HTML readers get
+responsive SVG and optional zoom controls; other builders retain Mermaid source.
+
+## Start with a working diagram
+
+The tutorial takes you from an empty directory to a page with a captioned,
+zoomable diagram.
+
+```{toctree}
+:maxdepth: 1
+:caption: Tutorial
+
+src/tutorial
+```
+
+## Solve an authoring task
+
+These guides cover existing Sphinx projects, visual customization, migration,
+and local checks.
+
+```{toctree}
+:maxdepth: 1
+:caption: How-to guides
+
+src/usage
+src/styling
+src/migration
+src/troubleshooting
+src/development
+```
+
+## Look up options and examples
+
+The reference records supported settings and their precedence. The example
+pages pair reusable source with output from the bundled renderer.
+
+```{toctree}
+:maxdepth: 1
+:caption: Reference
+
+src/configuration
+src/examples
+src/rst-examples
+```
+
+## Understand the rendering model
+
+Learn why diagrams render in the browser and what that means for layout,
+configuration, and non-HTML output.
+
+```{toctree}
+:maxdepth: 1
+:caption: Explanation
+
+src/rendering
+```

docs/src/configuration.md

@@ -1,5 +1,14 @@
 # Configuration reference
 
+## Requirements
+
+| Component        | Requirement                                                       |
+| ---------------- | ----------------------------------------------------------------- |
+| Python           | 3.11 or newer                                                     |
+| Sphinx           | 7.4 or newer                                                      |
+| MyST             | Optional, for Markdown documents                                  |
+| Node.js and pnpm | Needed to build from source; not needed to use an installed wheel |
+
 ## Sphinx settings
 
 | Setting              | Default | Meaning                                                             |
@@ -11,6 +20,8 @@ Pele 1.6.0 is bundled in the wheel. HTML documentation uses local JavaScript and
 CSS, with no CDN or Node.js runtime requirement. Building the package from source
 requires Node.js and pnpm.
 
+(diagram-configuration)=
+
 ## Diagram configuration
 
 The `pele` mapping in **diagram** YAML frontmatter accepts the same options as
@@ -46,6 +57,10 @@ The extension accepts these JSON-compatible [Pele options](https://pele.run/api)
 | `zoom`                                                   | Boolean, `auto`, or zoom options mapping |
 
 Zoom mappings accept Pele's `always`, `maxScale`, `controls`, and `labels` options.
+`labels` is a mapping with `zoomIn`, `zoomOut`, and `reset` strings. The default
+`zoom: "auto"` shows controls when a diagram shrinks to fit; `true` always enables
+zoom and `false` disables it. The documentation gallery explicitly disables zoom
+by default and enables it on selected examples.
 Pele supplies defaults for omitted values. Mounting measures the container width;
 `:width:` controls the container's available width. `maxWidth` is accepted for API
 compatibility but Pele's mount operation uses the measured width.
@@ -95,3 +110,21 @@ Pele zoom controls. Without JavaScript, escaped Mermaid source remains visible.
 Text, LaTeX, man, and other non-HTML builders emit source as a literal block;
 PDF/image export is not implemented. Mermaid CLI options, D3 zoom, and
 `sphinxcontrib.mermaid`'s class-tree generator are not supported.
+
+## Errors
+
+| Condition                                                   | Result                                                 |
+| ----------------------------------------------------------- | ------------------------------------------------------ |
+| Invalid `pele_options` or `pele_css_variables` in `conf.py` | Sphinx configuration error.                            |
+| Both Mermaid extensions enabled                             | Sphinx configuration error.                            |
+| Empty directive, missing file, or invalid directive option  | Document parsing error.                                |
+| Invalid diagram frontmatter or `pele` option                | `pele.config` warning; source remains a literal block. |
+| Missing packaged browser assets                             | HTML builder initialization error.                     |
+| Invalid Mermaid syntax or a rendering limit exceeded        | Browser error display from Pele.                       |
+
+The extension validates the top-level types of renderer options. Nested Mermaid
+settings and zoom mapping contents are passed to Pele; they do not receive a
+complete schema check in Python. Date-like YAML values must be quoted when used
+as strings; `now` accepts a numeric timestamp, not a YAML date.
+
+See [troubleshooting](troubleshooting.md) for recovery steps.

docs/src/development.md

@@ -0,0 +1,54 @@
+# How to build and check the documentation locally
+
+Start from a repository checkout with Python 3.11+, Node.js 22+, pnpm, and `uv`
+installed. Use pnpm 11.11.0 to match the CI setup used for this project.
+
+```sh
+uv venv
+. .venv/bin/activate
+make develop
+python -m sphinx -W -b html docs docs/_build/html
+python -m http.server 8000 --directory docs/_build/html
+```
+
+Open `http://localhost:8000/`. On Windows, activate the environment with
+`.venv\Scripts\activate`.
+
+## Add a gallery example
+
+Create a UTF-8 `.mmd` file in `docs/src/examples/`. In `docs/src/examples.md`, add a
+source listing and a rendering directive that both read it:
+
+````markdown
+## Review flow
+
+```{literalinclude} examples/review.mmd
+:language: text
+```
+
+```{mermaid} examples/review.mmd
+```
+````
+
+Use `text` for the source listing so it remains visible as code. A source listing
+with language `mermaid` would itself render as a second diagram.
+
+Update the gallery's expected diagram count in `js/tests/index.spec.js`. The
+browser checks should fail if a new example produces an error instead of SVG.
+
+## Run the checks
+
+```sh
+make lint
+make check-types
+make test
+python -m sphinx -W -b text docs docs/_build/text
+```
+
+`make test` runs Python integration tests and Chromium tests against built docs.
+Keep port 3000 available for the browser test server. For a docs-only edit,
+`make lint-docs` and `make test-js` provide the focused checks.
+
+Rebuild the bundle with `pnpm --dir js build` after editing browser code or
+updating Pele. Before changing packaging, also run `make build` and
+`make check-dist`.