stouputils.applications.automatic_docs.sphinx.highlighting package#

Editor-grade syntax highlighting for the Python code blocks of the generated documentation.

Two pieces are needed, and neither works without the other: styles supplies the VS Code palettes, and semantics supplies the token distinctions those palettes expect but that Pygments’ Python lexer does not make on its own.

register() wires both into Sphinx and must run before the first page is highlighted, which is why the generated conf.py calls it from its setup hook.

register_styles() → None[source]#

Make the two palettes resolvable by name, the way pygments.styles.get_style_by_name() expects.

The pygments.styles entry points declared in pyproject.toml are the real mechanism, and the only one a consumer other than this generator will see. Filling the lookup tables directly costs two lines on top, and keeps a build working from a checkout whose installed metadata predates those entry points.

register_lexers() → None[source]#

Install Python lexers carrying VSCodeSemanticFilter into Sphinx’s lexer table.

Sphinx narrows every Python language alias down to python, or to pycon when the block opens on >>>, then hands back any lexer registered under that name untouched. Filtering both therefore covers plain code blocks and doctests alike, and building them from Sphinx’s own lexer_classes keeps the options it would have applied, stripnl included.

register() → None[source]#

Register both the palettes and the filtered lexers.

Submodules#