Documentation#

"If it ain't documented, it's broken."

Documentation in Volto has two parts, narrative and Storybook.

Narrative documentation#

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 Makefile.

In Volto, all documentation commands are prefixed with docs-. You should run these commands from the root of the volto repository.

To see the all Make commands, use the following command.

make help

Else you can open Makefile to see other build formats.

Warnings from 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#

docs-html is the HTML version of the documentation.

make docs-html

Open /docs/_build/html/index.html in a web browser.

docs-livehtml#

docs-livehtml rebuilds Sphinx documentation on changes, with live-reload in the browser.

make docs-livehtml

Open http://127.0.0.1:8000/ in a web browser.

docs-linkcheck#

docs-linkcheck checks all links. See All links must be valid for configuration.

make docs-linkcheck

Open /docs/_build/linkcheck/output.txt for a list of broken links.

docs-linkcheckbroken#

docs-linkcheckbroken runs docs-linkcheck, but returns only errors and provides coloring on the console.

make docs-linkcheckbroken

Open /docs/_build/linkcheck/output.txt for a list of broken links.

docs-vale#

docs-vale checks for American English spelling, grammar, syntax, and the Microsoft Developer Style Guide.

make docs-vale

See the output on the console for suggestions.

See also

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 entry#

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 RichTextWidget component.

To build the Volto Storybook locally and test your entry, run the following command from the repository root.

make storybook-build