Sphinx Serializing HTML Extension

2.0.0 · active · verified Sun Mar 29

sphinxcontrib-serializinghtml is a Sphinx extension that outputs "serialized" HTML files, specifically in JSON and Pickle formats. This enables external applications or custom post-processing tools to consume documentation content without needing to parse raw HTML. The library is currently at version 2.0.0 and follows a release cadence tied to Sphinx releases, with recent updates addressing dependency management and Python/Sphinx version compatibility.

Warnings

breaking Python 3.5, 3.6, 3.7, and 3.8 support was dropped in version 1.1.6. Version 2.0.0 and later require Python >= 3.9.
Fix: Upgrade your Python environment to 3.9 or newer.
breaking The minimum required Sphinx version was raised to 5.0 in `sphinxcontrib-serializinghtml` version 1.1.6. Using older Sphinx versions with recent `sphinxcontrib-serializinghtml` releases will likely result in errors.
Fix: Ensure your Sphinx installation is version 5.0 or newer (e.g., `pip install -U Sphinx`).
gotcha Older versions (e.g., 1.1.1) of `sphinxcontrib-serializinghtml` experienced circular import issues if Sphinx was directly listed as a dependency, causing build failures. This was addressed in later 1.1.x versions, specifically version 1.1.10 removed Sphinx as a required direct dependency to prevent such conflicts.
Fix: Upgrade to `sphinxcontrib-serializinghtml` version 1.1.10 or later to avoid this specific circular import problem.
gotcha This extension provides special builders (`json` and `pickle`). To generate serialized output, you must explicitly use these builders (e.g., `make json` or `sphinx-build -b json`), not the default `html` builder. The output will be in `.fjson` and `.fpickle` files, not standard `.html`.
Fix: When building your Sphinx project, use `make json` or `make pickle` (or `sphinx-build -b json` / `sphinx-build -b pickle`) to generate the desired serialized output.

Install

pip install sphinxcontrib-serializinghtml Install latest version

Imports

sphinxcontrib.serializinghtml
```
# in conf.py
extensions = [
    'sphinxcontrib.serializinghtml'
]
```
This library is a Sphinx extension and should be enabled by adding its name (as a string) to the 'extensions' list in your Sphinx project's conf.py. Direct Python import statements are generally not used for enabling Sphinx extensions in conf.py, and historically caused circular import issues in older versions.

Quickstart

After installing the library, enable it by adding 'sphinxcontrib.serializinghtml' to the 'extensions' list in your Sphinx project's `conf.py`. Then, build your documentation using the 'json' or 'pickle' builder, which are provided by this extension.

# 1. Create a Sphinx project (if you don't have one):
# sphinx-quickstart

# 2. In your conf.py file, add the extension:
# extensions = [
#     'sphinxcontrib.serializinghtml'
# ]

# 3. Build the documentation to JSON or Pickle format:
# From your project root (where Makefile or make.bat is located):
# make json
# or
# make pickle

# Alternatively, using sphinx-build directly:
# sphinx-build -b json -d _build/doctrees . _build/json
# sphinx-build -b pickle -d _build/doctrees . _build/pickle

view raw JSON →