beanbag_docutils.sphinx.ext.json_writer

Sphinx extension offering an enhanced JSON document builder.

When enabled, the JSON builder provided by sphinxcontrib-serializinghtml will be augmented with:

  1. A toc key in globalcontext.json containing a structured Table of Contents for the site.

  2. An anchors_html in the page’s context containing HTML-rendered anchors for the page, without the page title being included.

Setup

To use this, add the extension in conf.py:

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

This will automatically enable the sphinxcontrib.serializinghtml extension and set the appropriate overrides.

You can then build the JSON documentation using the json builder.

Table of Contents Structure

The toc key in globalcontext.json contains a list of dictionaries containing:

Keys:

  • docname (str) – The name of the document.

  • title (str) – The document title.

  • items (list, optional) – The list of child documents under this page in the tree. This uses this same structure.

This will start with the index.rst at the top of the project, if it exists. If it does not, it will fall back to the configured Sphinx root document (configured by root_doc).

Anchors Structure

Anchors are stored in a .fjson page’s anchors_html key. This will be pre-rendered HTML, following the form of the normal toc key. For example:

<ul>
 <li><a class="reference internal" href="#section1">Section 1</a></li>
 <li><a class="reference internal" href="#section2">Section 2</a><ul>
  <li><a class="reference internal" href="#section2.1">Section 2.1</a></li>
  <li><a class="reference internal" href="#section2.2">Section 2.2</a></li>
  ...
 </ul></li>
 ...
</ul>

Functions

setup(app)

Set up the Sphinx extension.

Classes

JSONBuilder(app[, env])

Sphinx builder for JSON files.
class beanbag_docutils.sphinx.ext.json_writer.JSONBuilder(app: Sphinx, env: Optional[BuildEnvironment] = None)

Bases: JSONHTMLBuilder

Sphinx builder for JSON files.

This specializes sphinxcontrib.serializinghtml.JSONHTMLBuilder, adding additional state for a structured Table of Contents, available in glboalcontext.json.

New in version 2.2.

handle_finish()

Handle finishing the build for all the docs.

beanbag_docutils.sphinx.ext.json_writer.setup(app)

Set up the Sphinx extension.

This sets up the configuration and event handlers needed for the JSON writer extension.

New in version 2.2.

Parameters:

app (sphinx.application.Sphinx) – The Sphinx application to register configuration and listen to events on.