sphinx_better_subsection

Sphinx extension to prefer explicit IDs in sections

Add this extension using:

extensions += ["sphinx_better_subsection"]

Using the transformer directly is also allowed with:

from sphinx_better_subsection import PreferSectionTarget
app.add_transform(PreferSectionTarget)

Classes

PreferSectionTarget

Prefer target IDs over the section's own

Functions

setup

Sphinx extension entry point

Documentation

class sphinx_better_subsection.PreferSectionTarget(document, startnode=None)

Bases: Transform

Prefer target IDs over the section’s own

Given this input text:

.. _a:
.. _b:
.. _c:

Section Title
-------------

A paragraph.

This parses into:

...
    <target ids="['a']" names="['a']">
    <target ids="['b']" names="['b']">
    <target ids="['c']" names="['c']">
    <section ids="section-title" names="Section\ Title">
        ...

Transforming it gives:

...
    <target ids="['a']" names="['a']">
    <target ids="['b']" names="['b']">
    <target refid="c">
    <section ids="c section-title" names="c Section\ Title">
        ...

Note that the other IDs are all preserved; only the order is modified. Nested subsections are also checked.

Initial setup for in-place document transforms.

default_priority = 255

Numerical priority of this transform, 0 through 999 (override).

apply()

Docutils transform entry point

sphinx_better_subsection.setup(app)

Sphinx extension entry point