Sphinx themes and extensions
Sphinx 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.
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
We use several Sphinx extensions to enhance the presentation of Plone documentation.
sphinx.ext.graphvizallows you to embed Graphviz graphs in your documents.
sphinx.ext.intersphinxprovides linking between separate projects that use Sphinx for documentation.
sphinx.ext.todoadds support for todo items.
sphinx_copybuttonadds a little "copy" button to the right of code blocks.
sphinx-designadds grids, cards, icons, badges, buttons, tabs, and dropdowns.
sphinx_sitemapgenerates multiversion and multilanguage sitemaps.org compliant sitemaps.
sphinxcontrib.httpdomainprovides a Sphinx domain for describing HTTP APIs. It is used by Plone's REST API.
sphinxcontrib-httpdomainby 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.videoallows you to embed local videos as defined by the HTML5 standard.
sphinxext.opengraphgenerates OpenGraph metadata.
sphinx.ext.viewcodegenerates pages of source code modules and links between the source and the description. It is used by plone.api.
sphinx.ext.autosummarygenerates function/method/attribute summary lists. It is used by plone.api.