Better your Sphinx section IDs
Project description
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)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinx_better_subsection-0.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | d83aac654384b292f246b64adaa9f4a2dfe494a3ef2861f3229ee7ecd80d9de9 |
|
MD5 | b2ed6f8c8f62d8ffd8e47ed11e3ee9e9 |
|
BLAKE2b-256 | e1d329d2e2dd87b64aacf7147682a16ac6afe9bfe7a127b9e5f84b750a1c7963 |
Hashes for sphinx_better_subsection-0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0e602c0825f93eb11037128f49340267f93c63e12cc52d3fa3f852eb08ee7a4b |
|
MD5 | bff9ca0e4a045fe3090f2b764048a2e9 |
|
BLAKE2b-256 | 68bc8c5961a4ab33e0929e17929b51aecefa16ebcb08dadf395bcfcdd66f2730 |