sphinx-better-subsection 0.2

Better your Sphinx section IDs

Better your Sphinx section IDs.

This extension helps keep your permalinks permanent by allowing you to specify a section’s ID. As an example:

.. _v1.2.3:

v1.2.3 (2022-03-19)
-------------------

The permalink on the title will be #v1-2-3 instead of #v1-2-3-2022-03-19. When you change the section title later on, the permalink will still work.

Installation

Download and install this extension using pip:

$ pip install sphinx-better-subsection

Then add this extension in your conf.py:

extensions += ["sphinx_better_subsection"]

Usage

Add a reST internal hyperlink target (the .. _name: syntax) before your section. This extension moves that ID to the front of the IDs list, making the permalink the target’s ID instead of the generated ID from the title. When multiple are found, the last one is used.

This enhances existing reST to do the expected thing and also degrades gracefully when this extension isn’t used (such as in GitHub or online renderers).

Docutils

This package provides a docutils transformer called PreferSectionTarget (subclass of docutils.transforms.Transform) usable via:

from sphinx_better_subsection import PreferSectionTarget
document.transformer.add_transform(PreferSectionTarget)

MyST

As far as I can tell, this extension is compatible with MyST using its header target syntax (the (name)= syntax). The first example in MyST would be:

(v1.2.3)=
## v1.2.3 (2022-03-19)

Links

• Source Code: https://github.com/GeeTransit/sphinx-better-subsection

• Documentation: https://geetransit.github.io/sphinx-better-subsection/

• PyPI Releases: https://pypi.org/project/sphinx-better-subsection/