The Sphinx documentation for Multi-Workflow Support for Plone, built with MyST and the Plone Sphinx Theme.
Published at collective.github.io/collective-multiworkflow.
docs/
├── docs/ the documentation source; every page lives here
│ ├── conf.py Sphinx configuration, commented section by section
│ ├── index.md landing page
│ ├── tutorials/ learning-oriented
│ ├── how-to-guides/ task-oriented
│ ├── concepts/ understanding-oriented
│ └── reference/ information-oriented
├── styles/ Vale styles and the project vocabulary
├── Makefile every command below
└── pyproject.toml documentation dependencies
The four content directories are the quadrants of the Diátaxis framework. Each page belongs to exactly one of them: a page that both teaches and describes belongs in two pages.
uv manages the Python version and the dependencies.
curl -LsSf https://astral.sh/uv/install.sh | shEverything else is installed on first use by the Makefile.
| Command | What it does |
|---|---|
make html |
Build the HTML documentation into _build/html. |
make livehtml |
Rebuild on change and serve a live-reloading preview. |
make help |
List every target. |
While writing, make livehtml is the one to leave running.
CI runs all of these, and so should you before opening a pull request.
| Command | What it checks |
|---|---|
make html |
The build must produce zero warnings. |
make linkcheckbroken |
Every link resolves. |
make vale |
Spelling, grammar, and Microsoft-style prose. Fix errors; warnings and suggestions are advisory. |
make doctest |
Any doctest blocks still produce what they claim. |
make test |
All of the above, from a clean build. |
Vale checks docs/docs/**/*.md only, so this file is not linted.
A word Vale does not know goes in styles/config/vocabularies/Base/accept.txt, one regular expression per line.
Add a term there only when it is genuinely a term — a misspelling is not a vocabulary gap.
Two parts of the documentation are generated, and neither should be edited by hand.
The Python API reference under docs/reference/api/ is automodule and nothing else.
It renders the docstrings in backend/src/collective/multiworkflow/, so the docstrings are where an API description belongs.
pyproject.toml installs the backend package as an editable dependency, which is what lets autodoc follow the working tree instead of a stale snapshot.
The REST API examples in docs/reference/rest-api.md are the .req and .resp files under backend/tests/docs/http-examples/, written by the backend test suite.
Regenerate them with uv run pytest tests/docs from the backend directory.
A payload that changes shape therefore fails the backend suite rather than quietly outdating this documentation.
- One sentence per line. No sentence is ever broken across lines, and no line ever holds two. It keeps diffs readable and lets a reviewer comment on a single sentence.
- Sentence case headings, and filenames with dashes rather than underscores.
- American English, active voice, imperative mood for instructions.
html_metafrontmatter on every page, withdescriptionandproperty=og:descriptionidentical.- A label above every H1, named
<section>-<slug>—concepts-state-variables,howto-search-by-workflow-state— so other pages can cross-reference it. - One page owns each fact. Everything else links to it. Duplicated facts drift apart.
Admonitions are a tool of attention: one or two per page at most.
A note that restates the paragraph above it should be deleted.
These follow Plone's guide for documentation authors, which is the authority when this file is silent.
- Decide the quadrant. Is the reader learning, doing, looking something up, or trying to understand? That answer is the directory.
- Create the file with dashes in its name, and add it to the section
index.mdtoctree. - Write the frontmatter, the label, and the H1.
- Run
make testbefore committing.
The site is deployed to GitHub Pages on every push to main that touches the documentation or the frontend.
The documentation is published at the root, and Storybook under /storybook/, as one artifact — see .github/workflows/tmp-docs-publish.yml.
Both halves are rebuilt together on purpose: deploying one without the other would let the two drift apart.
Note
make clean removes the build directory and the virtual environment.
Use it when dependencies change; the next command reinstalls everything.
Generated using Cookieplone (2.0.0b3) and cookieplone-templates (61a8f90) on 2026-08-07 16:01:41.322560. A special thanks to all contributors and supporters!