Skip to content

beanbaginc/beanbag-docutils

Repository files navigation

Beanbag Doc Utilities

This is a collection of utilities to help with generating documentation for Beanbag-related products, including:

  • Review Board - Our widely-used open source code review product.
  • RBCommons - Our Review Board SaaS.
  • Djblets - A set of utilities and infrastructure for Django-based projects.
  • RBTools - Command line tools for Review Board and RBCommons.

Sphinx Extensions

Most of the utilities are used with the Sphinx documentation system. 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

Compatibility

  • beanbag-docutils 3.x supports Python 3.8-3.13 and Sphinx 5.0-7.x.
  • beanbag-docutils 2.x supports Python 3.6-3.12 and Sphinx 1.8-7.x.
  • beanbag-docutils 1.x supports Python 2.7 and 3.6-3.10.

Getting Started

To install the package, run:

$ pip install beanbag-docutils

See the documentation for usage information.