document-readable (TN203)#
Group |
Default severity |
|---|---|
Content |
Error |
Sphinx must be able to read the technote’s document. The rules about what a technote publishes — its abstract, and the title it is cited by — get their answer by building the technote (The linter builds the technote), so a document that does not read leaves them with nothing to report on, and this rule reports the read failure instead, carrying Sphinx’s own message.
The common causes are an index.ipynb notebook that is not valid JSON (from a botched merge conflict resolution, a truncated save, or hand editing), a conf.py that raises, and a technote directory that has a conf.py but no index file for Sphinx to build.
Example of a failing technote#
A merge conflict left markers in the notebook file, so it is no longer valid JSON:
{
"cells": [
<<<<<<< HEAD
{"cell_type": "markdown", ...
[TN203] index.ipynb could not be read by Sphinx: Notebook does not appear to be JSON: '{\n "cells": [\n<<<<<<< HEAD...
How to fix it#
Repair the file so it is valid JSON again:
If the damage came from a merge conflict, resolve the conflict markers — for notebooks, a tool such as nbdime merges notebook JSON structurally.
Otherwise, restore the last good version from git (
git checkout <commit> -- index.ipynb) and re-apply your changes by editing the notebook in Jupyter, which always saves valid JSON.