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-in image 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

Sphinx Extensions

beanbag_docutils.sphinx.ext

beanbag_docutils.sphinx.ext.autodoc_utils

Sphinx extension to add utilities for autodoc.

beanbag_docutils.sphinx.ext.collect_files

Sphinx extension to collect additional files in the build directory.

beanbag_docutils.sphinx.ext.django_utils

Sphinx extension to add useful Django-related functionality.

beanbag_docutils.sphinx.ext.extlinks

Sphinx extension to define external links that support anchors.

beanbag_docutils.sphinx.ext.github

Sphinx extension to link to source code on GitHub.

beanbag_docutils.sphinx.ext.http_role

Sphinx extension to add a http role for docs.

beanbag_docutils.sphinx.ext.image_srcsets

Sphinx extension for srcsets in images.

beanbag_docutils.sphinx.ext.intersphinx_utils

Sphinx extension to enhance intersphinx support.

beanbag_docutils.sphinx.ext.json_writer

Sphinx extension offering an enhanced JSON document builder.

beanbag_docutils.sphinx.ext.metadata

Sphinx extension for extracting metadata for the page.

beanbag_docutils.sphinx.ext.ref_utils

Sphinx extension to improve references.

beanbag_docutils.sphinx.ext.retina_images

Sphinx extension for Retina images.

Release Notes

beanbag-docutils 2.3

Release date: October 15, 2023

Packaging / Compatibility

  • Added support for Sphinx 7.2.

beanbag_docutils.sphinx.ext.image_srcsets

  • Images with widths/heights now have width and height attributes set.

    Sphinx turns widths and heights into style="width: ...; height: ..." attributes, but does not set the dedicated width and height attributes. These attributes are helpful for the browser when computing layout and aspect ratios, and are not deprecated or strictly interchangeable with the CSS styles.

    This extension now sets these attributes and strips them out of any CSS styling.

Contributors

  • Christian Hammond

  • David Trowbridge

  • Michelle Aubin

beanbag-docutils 2.2

Release date: June 19, 2023

Packaging / Compatibility

  • Added support for Python 3.12.

  • Added support for Sphinx 6 and 7.

New Extensions

  • Added a new metadata Sphinx extension for extracting additional page metadata.

    This extension extracts any meta information (useful for content like page descriptions for social media) and extracts their information into the document’s top-level metadata.

    This metadata can then be used when building sites or tools that process the page’s compiled documentation (when not simply relying on the generated HTML).

    The metadata will be available in the document’s meta information, keyed off by the name used in the meta directive, the content, and any other attributes provided.

    If multiple pieces of metadata exist for the same key, the information will be assembled into a list under that key. Otherwise, the information will be assigned directly to the key.

  • Added a new json_writer Sphinx extension for enhanced JSON writing.

    This augments the JSON writer typically found in the sphinxcontrib-serializinghtml package to include two new pieces of information:

    1. A structured representation of the Table of Contents for the whole doc bundle.

    2. Rendered HTML for the anchors in the page (similar to the “toc” available in the page, but without the page’s own header).

    These can be used by consumers to pull out this structured information without having to parse the docsets themselves, helping provide a dynamic Table of Contents.

Contributors

  • Christian Hammond

  • David Trowbridge

  • Michelle Aubin

beanbag-docutils 2.1.1

Release date: February 28, 2023

beanbag_docutils.sphinx.ext.image_srcsets

  • Fixed automatically scanning and collecting multi-DPI images for the generated documentation.

Contributors

  • Christian Hammond

  • David Trowbridge

beanbag-docutils 2.1

Release date: February 4, 2023

Packaging / Compatibility

  • Added support for Sphinx 6.

  • Updated the Sphinx dependency to require version 4 or higher.

  • Removed a dependency on six.

beanbag_docutils.sphinx.ext.autodoc_utils

  • Fixed performing incremental builds.

    Due to a bug, all builds were being treated as full builds.

  • __annotations__ are now excluded from generated docs by default.

beanbag_docutils.sphinx.ext.github

  • Added support for custom GitHub URLs.

    A GitHub URL (useful for GitHub Enterprise) can now be set by passing github_url= to github_linkcode_resolve().

  • Fixed generating links to GitHub when failing to resolve tracking branches.

    These links were appearing broken before. Now, if a tracking branch can’t be resolved, the links will point to the file on GitHub without a stable SHA.

beanbag_docutils.sphinx.ext.image_srcsets

  • Added the new image_srcsets Sphinx extension.

    This extension enables multi-DPI/responsive images to be used in generated documentation.

    It’s intended to replace image and can be used like:

    .. image:: path/to/file.png
   :sources: 2x path/to/file@2x.png
             3x path/to/file@3x.png
             100w path/to/file@100w.svg
             200h path/to/file@200h.svg

Contributors

  • Christian Hammond

  • David Trowbridge

  • Michelle Aubin

beanbag-docutils 2.0

Release date: August 17, 2022

Compatibility

  • Dropped support for Python 2.7 and added Python 3.11.

    Beanbag Docutils now supports 3.6 through 3.11.

beanbag_docutils.sphinx.ext.autodoc_utils

  • This module now sets a handful of default Sphinx configuration settings:

    extensions = [
    'sphinx.ext.autodoc,',
    'sphinx.ext.intersphinx',
    'sphinx.ext.napoleon',
]

autodoc_member_order = 'bysource'
autoclass_content = 'class'
autodoc_default_options = {
    'members': True,
    'special-members': True,
    'undoc-members': True,
    'show-inheritance': True,
}

    To disable these defaults, set:

    use_beanbag_autodoc_defaults = False

  • Added support for a Keys section.

    This is used to document dictionaries and other similar content. It works as a section nested within a paragraph and resembles Args or Attributes.

    For example:

    Here is a description of some dictionary:

Keys:
    key1 (str):
       Description of the key.

    key2 (collections.OrderedDict, optional):
       And a description of another key.

  • Added support for a Tuple section.

    This is used to document tuples. It also works as a section nested within a paragraph, and resembles Args or Attributes.

    For example:

    Here is a description of some tuple:

Tuple:
    1 (int):
       Description of the first item.

    2 (bool):
       And a description of the second.

    3 (django.db.models.Model):
       And finally the third.

  • Added support for a Type section.

    This is used to document the type of an attribute or property. It works similarly to a Returns section, with the description being optional.

    For example:

    This attribute does a thing.

Type:
    path.to.MyObject

  • Fixed including list items in Version Added, Version Changed, and Deprecated sections.

beanbag_docutils.sphinx.ext.github

  • Improved several aspects of linking to Python code on GitHub.

    This can now handle linking to attributes, variables, and dynamically-generated objects like named tuples.

    The entire way of linking has been redone, now taking advantage of the Python AST to determine the correct line numbers to content, rather than an older approach that only supported typical classes, functions, and methods.

  • Fixed regressions in linking to code on GitHub when building on Python 3.

Contributors

  • Christian Hammond

  • David Trowbridge

beanbag-docutils 1.9

Release date: July 26, 2022

Compatibility Improvements

  • Added compatibility with Sphinx 5.x.

  • Updated the Sphinx dependency to not specify a range. It’s now completely in the hands of the consuming codebase.

Contributors

  • Christian Hammond

beanbag-docutils 1.8.1

Release date: August 1, 2021

Compatibility Improvements

  • Added compatibility with Sphinx 4.x+.

Bug Fixes

Contributors

  • Christian Hammond

beanbag-docutils 1.8

Release date: February 27, 2021

Compatibility Improvements

  • Added compatibility for Django 3.x.

  • Added compatibility with Sphinx 3.x+.

    The correct version is now used depending on the version of Python.

Project Changes

  • Universal wheels are now built for Python 2 and 3 compatibility.

  • Added documentation for beanbag-docutils.

  • Added a unit test suite.

Bug Fixes

  • Fixed a syntax error with http with HTTP 418 on Python 3.

Contributors

  • Christian Hammond

beanbag-docutils 1.7.1

Release date: August 5, 2020

Compatibility Changes

  • Capped the Sphinx version to >=1.7.1, <2.0.

Bug Fixes

Contributors

  • Christian Hammond

beanbag-docutils 1.7

Release date: June 14, 2018

New Features

  • Added compatibility with Python 3.

    This package now supports Python 2.7 and 3.4 through 3.6.

  • Added new documentation sections for the Beanbag documentation format.

    This is enabled when using beanbag_docutils.sphinx.ext.autodoc_utils with napoleon_beanbag_docstring = True.

    This adds:

    Deprecated:

    A version in which something is deprecated, and an optional description. This is similar to the ReST deprecated directive.

    Version Added:

    A version in which something is added, and an optional description. This is similar to the ReST versionadded directive.

    Version Changed:

    A version in which something is changed, and an optional description. This is similar to the ReST versionchanged directive.

  • Added a Sphinx extension (beanbag_docutils.sphinx.ext.ref_utils) for improving code references.

    This currently enhances references, allowing both Python and JavaScript references to break paths (like foo.bar.MyClass) across multiple lines.

    To install this extension, add the following to your conf.py:

    extensions = [
    ...
    'beanbag_docutils.sphinx.ext.ref_utils',
    ...
]

Bug Fixes

  • Fixed handling of multi-line argument types when using the Beanbag documentation format support.

    This addresses a case where spaces after a type (such as int, optional) would be lost.

Contributors

  • Christian Hammond

beanbag-docutils 1.6

Release date: November 16, 2017

New Features

  • Added custom titles for HTTP error codes in http.

Contributors

  • Christian Hammond

beanbag-docutils 1.5

Release date: November 10, 2017

New Features

Bug Fixes

Contributors

  • Christian Hammond

beanbag-docutils 1.4.1

Release date: October 4, 2017

New Features

Contributors

  • Christian Hammond

beanbag-docutils 1.4

Release date: May 25, 2017

New Features

  • Added a parser for the Beanbag documentation format.

    This is part of beanbag_docutils.sphinx.ext.autodoc_utils, and is enabled when setting napoleon_beanbag_docstring = True in conf.py. It replaces the Google and Numpy docstring formats, but requires sphinx.ext.napoleon.

    This currently supports:

    Context:

    Describes what happens within the context of a context manager.

    Model Attributes:

    Describes the attributes on a Backbone.js model.

    Option Args:

    Describes options available to a function in JavaScript.

    This parser also allows types (used in Args and other sections) to be wrapped across lines.

Contributors

  • Christian Hammond

beanbag-docutils 1.3

Release date: May 23, 2017

New Features

  • Added beanbag_docutils.sphinx.ext.intersphinx_utils, which adds new features for intersphinx lookups.

    This adds a default-intersphinx directive that allows for specifying one or more intersphinx set prefixes that should be tried if a reference could not be found. For example:

    .. default-intersphinx:: myapp1.5, python

:ref:`some-reference`

    This does affect the process by which missing references are located. If an unprefixed reference is used, it will only match if the prefix is in the list above, which differs from the default behavior of looking through all intersphinx mappings.

    This also works around an issue with option (see https://github.com/sphinx-doc/sphinx/pull/3769 for the equivalent upstream fix).

Contributors

  • Christian Hammond

beanbag-docutils 1.2

Release date: January 21, 2017

New Features

  • Added beanbag_docutils.sphinx.ext.collect_files for collecting additional files in a build.

    This is used to copy files (indicated by glob patterns) from the source directory into the destination build directory. Each destination file will be in the same relative place in the tree.

    This is useful when you have non-ReST/image files that you want part of your built set of files, perhaps containing metadata or packaging that you want to ship along with the documentation.

    To use this, you just need to add the extension in conf.py:

    extensions = [
    ...
    'beanbag_docutils.sphinx.ext.collect_files',
    ...
]

    And then configure collect_file_patterns to be a list of filenames/glob patterns, like:

    collect_file_patterns = ['metadata.json', '*.pdf']

Contributors

  • Christian Hammond

beanbag-docutils 1.1

Release date: November 18, 2016

New Features

  • Added beanbag_docutils.sphinx.ext.extlinks for defining anchor-aware external links.

    Sphinx ships with a sphinx.ext.extlinks extension, which allows for defining roles that map to external links. These take a URL that work as a format string, containing a %s. The reference is then passed into that, and the result is a URL embedded in the page.

    This is very useful, but has a flaw in that anchors do not work with these links. If the format string has any content after the %s, then that content will appear after the anchor. Support for this is being tracked upstream by Sphinx, but as of yet there isn’t any indication of a plan to implement anchor support.

    This extension adds that anchor support, building upon the logic in Sphinx’s extension and adding a shim that handles anchor-safe string formatting. It’s a drop-in replacement that can be used without changing any configuration, meaning we can remove it down the road without any real work if Sphinx ends up fixing this upstream.

Contributors

  • Christian Hammond

beanbag-docutils 1.0

Release date: July 19, 2016

Initial release, featuring:

autodoc_utils

Enhances autodoc support to allow for excluding content from docs.

A module can define top-level __autodoc_excludes__ or __deprecated__ lists. These are in the same format as __all__, in that they take a list of strings for top-level classes, functions, and variables. Anything listed here will be excluded from any autodoc code.

__autodoc_excludes__ is particularly handy when documenting an __init__.py that imports contents from a submodule and re-exports it in __all__. In this case, autodoc would normally output documentation both in __init__.py and the submodule, but that can be avoided by setting:

__autodoc_excludes = __all__

Excludes can also be defined globally, filtered by the type of object the docstring would belong to. See the documentation for autodoc-skip-member for more information. You can configure this in conf.py by doing:

autodoc_excludes = {
    # Applies to modules, classes, and anything else.
    '*': [
        '__dict__',
        '__doc__',
        '__module__',
        '__weakref__',
    ],
    'class': [
        # Useful for Django models.
        'DoesNotExist',
        'MultipleObjectsReturned',
        'objects',

        # Useful forms.
        'base_fields',
        'media',
    ],
}

That’s just an example, but a useful one for Django users.

To install this extension, add the following to your conf.py:

extensions = [
    ...
    'beanbag_docutils.sphinx.ext.autodoc_utils',
    ...
]

django_utils

Adds some improvements when working with Django-based classes in autodocs, and when referencing Django documentation.

First, this will take localized strings using ugettext_lazy() and turn them into actual strings, which is useful for forms and models.

Second, this adds linking for setting-based documentation, allowing custom settings (from django.conf.settings) to be documented and referenced, like so:

.. setting:: MY_SETTING

Settings go here.

And then to reference it: :setting:`MY_SETTING`.

To install this extension, add the following to your conf.py:

extensions = [
    ...
    'beanbag_docutils.sphinx.ext.django_utils',
    ...
]

github_linkcode

Links source code for modules, classes, etc. to the correct line on GitHub. This prevents having to bundle the source code along with the documentation, and better ties everything together.

To use this, simply add the following to conf.py:

from beanbag_docutils.sphinx.ext.github import github_linkcode_resolve

extensions = [
    ...
    'sphinx.ext.linkcode',
    ...
]

linkcode_resolve = github_linkcode_resolve

http_role

Provides references for HTTP codes, linking to the matching docs on Wikipedia.

To create a link, simply do:

This is :http:`404`.

If you want to use a different URL, you can add the following to conf.py:

http_status_codes_url = 'http://mydomain/http/%s'

Where %s will be replaced by the HTTP code.

To install this extension, add the following to your conf.py:

extensions = [
    ...
    'beanbag_docutils.sphinx.ext.http_role',
    ...
]

retina_images

Copies all Retina versions of images (any with a @2x filename) into the build directory for the docs. This works well with scripts like retina.js.

To install this extension, add the following to your conf.py:

extensions = [
    ...
    'beanbag_docutils.sphinx.ext.retina_images',
    ...
]

Contributors

  • Christian Hammond

  • 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.