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
Sphinx Extensions¶
The following extensions are provided:
autodoc_utils
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.
collect_files
Allows arbitrary supplemental files to be “collected” along with any of your documentation.
django_utils
Roles and directives for describing Django-related concepts in your documentation.
Automatic support for resolving “lazy” localized strings, so they appear correctly.
extlinks
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`
).
github
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.
http_role
Provides a
http
role for specifying HTTP status codes and linking them to useful documentation.
image_srcsets
Drop-in support for generating
<img srcset="...">
images using the built-inimage
directive. Appropriate images can be automatically determined or manually specified.
intersphinx_utils
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.
json_writer
An enhanced JSON writer that contains structured data for the docs-wide Table of Contents, and HTML for in-page anchors for docs.
New in version 2.2.
metadata
Extracts metadata from
meta
directives into the document’s metadata, allowing tools or custom doc rendering platforms to access it.
New in version 2.2.
ref_utils
Allows Python and JavaScript references to span multiple lines, in case of very long class or module paths.
retina_images
Collects all high-DPI versions of images (e.g., any with a
@2x
in the filename) for the resulting documentation.
See Also¶
- Release Notes
- beanbag-docutils 2.2
- beanbag-docutils 2.1.1
- beanbag-docutils 2.1
- beanbag-docutils 2.0
- beanbag-docutils 1.9
- beanbag-docutils 1.8.1
- beanbag-docutils 1.8
- beanbag-docutils 1.7.1
- beanbag-docutils 1.7
- beanbag-docutils 1.6
- beanbag-docutils 1.5
- beanbag-docutils 1.4.1
- beanbag-docutils 1.4
- beanbag-docutils 1.3
- beanbag-docutils 1.2
- beanbag-docutils 1.1
- beanbag-docutils 1.0
Other Projects:
Review Board - Our extensible open source code review product.
RBCommons - Our Review Board SaaS.
Django Evolution - Advanced schema migration for Django, compatible with Django’s migrations.
Djblets - A set of utilities and infrastructure for Django-based projects.
kgb - Function spies for Python unit tests.
RBTools - Command line tools for Review Board and RBCommons.