Themes and extensions

The Plone Documentation team learned the hard way that maintaining the design and features of documentation is a lot of work. To make all documentation maintainable, we use actively developed themes and extensions to build the documentation.

Themes

When customizing the theme, we use Sphinx Book Theme, which in turn depends on PyData Sphinx Theme. See their documentation for features, tips, and tricks that you might want to include in your documentation.

We minimize the customizations of these themes as much as possible.

Extensions

We use several MyST and Sphinx extensions to enhance the presentation of Plone documentation.

MyST

• attrs_block supports parsing of block attributes before certain block syntaxes.

• attrs_inline supports parsing of inline attributes before certain inline syntaxes.

• colon_fence supports the use of three colons ::: as delimiters to denote code fences, instead of three backticks ```.

• deflist supports definition lists.

• html_image supports the use of HTML <img> tags.

• linkify identifies "bare" web URLs and adds hyperlinks.

• strikethrough supports the use of strikethrough markup.

• substitution supports the use of substitutions with Jinja2.

Sphinx

• myst_parser parses MyST, a rich and extensible flavour of Markdown for authoring documentation.

• sphinx-design, with a configuration name of sphinx_design, adds grids, cards, icons, badges, buttons, tabs, and dropdowns.

• sphinx-examples adds "example snippets" that allow you to show off source Markdown and the result of rendering it in Sphinx.

• sphinx-notfound-page, with a configuration name of notfound.extension, creates a custom 404 page and helps generate proper static resource links to render the page.

• sphinx-tippy, with a configuration name of sphinx_tippy, provides hover tips in your documentation.

• sphinx.ext.autodoc pulls in documentation from Python docstrings to generate reStructuredText which in turn gets parsed by Sphinx and rendered to the output format. It's used by plone.api.

• sphinx.ext.autosummary generates function/method/attribute summary lists. It's used by plone.api.

• sphinx.ext.graphviz allows you to embed Graphviz graphs in your documents.

• sphinx.ext.ifconfig includes content based on configuration.

• sphinx.ext.intersphinx provides linking between separate projects that use Sphinx for documentation.

• sphinx.ext.todo adds support for todo items.

• sphinx.ext.viewcode generates pages of source code modules and links between the source and the description. It's used by plone.api.

• sphinx_copybutton adds a little "copy" button to the right of code blocks.

• sphinx_reredirects handles redirects for moved pages.

• sphinx_sitemap generates multiversion and multilanguage sitemaps.org compliant sitemaps.

• sphinxcontrib.httpdomain provides a Sphinx domain for describing HTTP APIs. It's used by Plone's REST API.

• sphinxcontrib.httpexample enhances sphinxcontrib-httpdomain by generating RESTful HTTP API call examples for different tools from a single HTTP request example. Supported tools include curl, wget, httpie, and python-requests. It's used by Plone's REST API.

• sphinxcontrib.mermaid allows you to embed Mermaid graphs in your documents, including general flowcharts, sequence diagrams, and Gantt charts.

• sphinxcontrib.video allows you to embed local videos as defined by the HTML5 standard.

• sphinxcontrib.youtube allows you to embed remotely hosted videos from YouTube, Vimeo, or PeerTube.

• sphinxext.opengraph generates OpenGraph metadata.