beanbag-docutils Releases

beanbag-docutils 2.2: Enhanced JSON Output

Christian Hammond

beanbag-docutils is our collection of extensions for the Sphinx documentation platform.

This is a major feature release that introduces some new capabilities for JSON output, making it easier to integrate documentation into your own sites:

  • The metadata extension extracts .. meta:: into the JSON output for a page.
  • The json_writer extension replaces the sphinxcontrib-serializinghtml JSON writer and includes both a copy of the docs-wide Table of Contents structure in the globalcontext.fjson file and per-page anchor navigation HTML in the page’s .fjson file.

You can see how we make use of these new capabilities in the brand-new Review Board documentation site.

Installation

$ pip3 install beanbag-docutils==2.2

Learn More

Read More

beanbag-docutils 1.8: Sphinx 3 and Django 3

Christian Hammond

beanbag-docutils is a set of extensions to the Sphinx ReStructuredText-based documentation system used by our products to help generate better documentation. Amongst other enhancements, it provides:

  • 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

Today’s release of beanbag-docutils 1.8 features:

  • Compatibility with Sphinx 1.7 through the latest 3.x (as of this writing, 3.5.1)
  • Compatibility with Django 3.x (when using the django_utils extension)
  • New documentation, which we’ll be expanding over time.

See the release notes for the full list of changes.

Read More