# 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: BuildEnvironment)

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

  Added in version 2.2.

  __firstlineno__ = 90
  __static_attributes__ = ()
  handle_finish() → None

    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.

  Added in version 2.2.

  Parameters:

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