beanbag-docutils¶

This is a set of extensions to the Sphinx ReStructuredText-based documentation system used by our products to help generate better documentation

Amongst other enhancements, this package offers:

A parser for the Beanbag docstring format (a variation on the Google docstring format), which we use for Python and JavaScript documentation
Enhancements for Sphinx’s intersphinx system to provide per-page intersphinx resolution options (useful for pages, such as release notes, that need to link to different versions of the same docs, such as Django or Python)
Enhancements to ReStructuredText references to let a reference name span lines (useful for long Python/JavaScript module/class names)
Linking code references to GitHub documentation
High-DPI image embedding
A role for HTTP status codes
Access to document-defined metadata in a structured form when parsing documents

Installation¶

It’s very easy to get going. Just install beanbag-docutils like so:

$ pip install beanbag-docutils

We like to place ours in a doc-requirements.txt file in each of our repositories, and use:

$ pip install -r doc-requirements.txt

The following extensions are provided:

Enables parsing of the Beanbag docstring format for Python.
Advanced options for defining excluded and deprecated classes/functions to skip, either in a Sphinx project’s conf.py or directly in the Python modules.

Allows arbitrary supplemental files to be “collected” along with any of your documentation.

Roles and directives for describing Django-related concepts in your documentation.
Automatic support for resolving “lazy” localized strings, so they appear correctly.

An improved version of Sphinx’s own sphinx.ext.extlinks that supports anchors in the string passed to the role (e.g., :myext:`name#anchor`).

Provides links to the appropriate versions of the tree in GitHub for any source code references, instead of bundling copies of the source code with the documentation.

Provides a http role for specifying HTTP status codes and linking them to useful documentation.

Drop-in support for generating <img srcset="..."> images using the built-in image directive. Appropriate images can be automatically determined or manually specified.

Allows individual documentation pages to specify which intersphinx mappings should be used if multiple mappings contained the same reference. Useful for having, say, different release notes pages linking to different versions of Python or Django documentation.

An enhanced JSON writer that contains structured data for the docs-wide Table of Contents, and HTML for in-page anchors for docs.

Added in version 2.2.

Extracts metadata from meta directives into the document’s metadata, allowing tools or custom doc rendering platforms to access it.

Added in version 2.2.

Allows Python and JavaScript references to span multiple lines, in case of very long class or module paths.

Collects all high-DPI versions of images (e.g., any with a @2x in the filename) for the resulting documentation.