Themes and extensions
Contents
Themes and extensions#
We 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.
The one large customization is the search filter by part of the documentation, implemented in modifcations to the templates, _static/searchtools.js
, and the CSS file _static/custom.css
.
Extensions#
We use several MyST and Sphinx extensions to enhance the presentation of Plone documentation.
MyST#
deflist
supports definition lists.linkify
identifies "bare" web URLs and adds hyperlinks.colon_fence
supports the use of three colons:::
as delimiters to denote code fences, instead of three backticks```
.substitution
supports the use of substitutions with Jinja2.html_image
supports the use of HTML<img>
tags.
Sphinx#
myst_parser
parses MyST, a rich and extensible flavour of Markdown for authoring documentation.sphinx-design
, with a configuration name ofsphinx_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 ofnotfound.extension
, creates a custom 404 page and helps generate proper static resource links to render the page properly.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 is used by plone.api.sphinx.ext.autosummary
generates function/method/attribute summary lists. It is 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 is 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 is used by Plone's REST API.sphinxcontrib.httpexample
enhancessphinxcontrib-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 is used by Plone's REST API.sphinxcontrib.video
allows you to embed local videos as defined by the HTML5 standard.sphinxext.opengraph
generates OpenGraph metadata.