"If it ain't documented, it's broken."
Volto follows the guidance of Plone 6 Documentation and uses the same tools when writing narrative documentation.
We use Sphinx to build and check documentation.
We use MyST, an extended flavor of Markdown that allows the use of reStructuredText and Sphinx extensions to provide a rich experience.
The Plone 6 Documentation also provides excellent references for writing high quality narrative documentation.
Building and checking the quality of narrative documentation#
You can use Make commands to run Sphinx to build and check documentation.
All build and check documentation commands use the file
In Volto, all documentation commands are prefixed with
You should run these commands from the root of the
To see the all Make commands, use the following command.
Else you can open
Makefile to see other build formats.
make docs-* commands#
When running any of the documentation Make commands, you may safely ignore warnings such as the following:
/system-file-to-path/volto/docs/source/news/5294.breaking: WARNING: document isn't included in any toctree
These warnings only check each of the changelog entries for valid MyST syntax. We do not want to include them in the documentation through a toctree entry, because the release process copies them into the Volto Release Notes and deletes them. Thus it is safe to ignore warnings of this specific type, but you should heed all others.
docs-html is the HTML version of the documentation.
/docs/_build/html/index.html in a web browser.
docs-livehtml rebuilds Sphinx documentation on changes, with live-reload in the browser.
Open http://127.0.0.1:8000/ in a web browser.
docs-vale checks for American English spelling, grammar, syntax, and the Microsoft Developer Style Guide.
See the output on the console for suggestions.
See American English spelling, grammar, and syntax, and style guide for basic usage.
See Advanced Vale usage for Vale configuration, integration with popular IDEs, and other tips.
Storybook is a tool that demonstrates the visual elements in a system. Storybook provides a sandbox to build, test, and document these visual elements (components) in isolation, mock them to show different data, test edge cases.
Components include widgets, blocks, and basic and structural items.
When you develop a component, we encourage you to create or update its Volto Storybook entry.
As an example of how to do that, you can copy the existing Storybook entry for the
To build the Volto Storybook locally and test your entry, run the following command from the repository root.