1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
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
.. _Beanbag docstring format:
https://www.notion.so/reviewboard/Standard-Documentation-Format-4388f594d86547cc949b365cda3cf391
.. _Django: https://www.djangoproject.com/
.. _Google docstring format:
https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings
.. _intersphinx:
https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
.. _our products: https://www.beanbaginc.com/
.. _ReStructuredText:
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
.. _Sphinx: https://www.sphinx-doc.org/
Installation
============
It's very easy to get going. Just install ``beanbag-docutils`` like so:
.. code-block:: shell
$ pip install beanbag-docutils
We like to place ours in a :file:`doc-requirements.txt` file in each of our
repositories, and use:
.. code-block:: shell
$ pip install -r doc-requirements.txt
Sphinx Extensions
=================
The following extensions are provided:
:py:mod:`~beanbag_docutils.sphinx.ext.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 :file:`conf.py` or directly in the
Python modules.
:py:mod:`~beanbag_docutils.sphinx.ext.collect_files`
* Allows arbitrary supplemental files to be "collected" along with any of
your documentation.
:py:mod:`~beanbag_docutils.sphinx.ext.django_utils`
* Roles and directives for describing Django-related concepts in your
documentation.
* Automatic support for resolving "lazy" localized strings, so they
appear correctly.
:py:mod:`~beanbag_docutils.sphinx.ext.extlinks`
* An improved version of Sphinx's own :py:mod:`sphinx.ext.extlinks` that
supports anchors in the string passed to the role (e.g.,
``:myext:`name#anchor```).
:py:mod:`~beanbag_docutils.sphinx.ext.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.
:py:mod:`~beanbag_docutils.sphinx.ext.http_role`
* Provides a :rst:role:`http` role for specifying HTTP status codes and
linking them to useful documentation.
:py:mod:`~beanbag_docutils.sphinx.ext.image_srcsets`
* Drop-in support for generating ``<img srcset="...">`` images using the
built-in :rst:dir:`image` directive. Appropriate images can be
automatically determined or manually specified.
:py:mod:`~beanbag_docutils.sphinx.ext.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.
:py:mod:`~beanbag_docutils.sphinx.ext.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.
.. versionadded:: 2.2
:py:mod:`~beanbag_docutils.sphinx.ext.metadata`
* Extracts metadata from :rst:dir:`meta` directives into the document's
metadata, allowing tools or custom doc rendering platforms to access it.
.. versionadded:: 2.2
:py:mod:`~beanbag_docutils.sphinx.ext.ref_utils`
* Allows Python and JavaScript references to span multiple lines, in
case of very long class or module paths.
:py:mod:`~beanbag_docutils.sphinx.ext.retina_images`
* Collects all high-DPI versions of images (e.g., any with a ``@2x``
in the filename) for the resulting documentation.
See Also
========
.. toctree::
:hidden:
coderef/index
.. toctree::
:maxdepth: 2
releasenotes/index
* 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.
.. _Django Evolution: https://django-evolution.readthedocs.io/
.. _Djblets: https://github.com/djblets/djblets/
.. _kgb: https://github.com/beanbaginc/kgb/
.. _RBCommons: https://www.rbcommons.com/
.. _RBTools: https://github.com/reviewboard/rbtools/
.. _Review Board: https://www.reviewboard.org/
|
