Registry / sphinx-multitoc-numbering
Install & Compatibility
Where this runs
tested against v0.1.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 92.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.4s · import 0.000s · 93MB
94MB installed
● package 94MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
sphinx_multitoc_numbering
✓ extensions = [
"sphinx.ext.autodoc",
"sphinx_multitoc_numbering"
]
Add 'sphinx_multitoc_numbering' to the `extensions` list in your Sphinx project's conf.py to enable the extension. No direct Python import is typically needed by user code, as Sphinx loads extensions by name.
To quickly enable `sphinx-multitoc-numbering`, first install it via pip. Then, add `sphinx_multitoc_numbering` to your `extensions` list in `conf.py`. Finally, ensure your `toctree` directives include the `:numbered:` option (for reStructuredText) or `numbered: true` (for Jupyter Book's `_toc.yml`) to activate section numbering. The extension will then ensure continuous numbering across documents linked in the toctree.
# conf.py
# ...
project = 'My Multi-Part Documentation'
copyright = '2024, Your Name'
extensions = [
'sphinx.ext.autodoc',
'sphinx_multitoc_numbering'
]
# ...
# index.rst (or your master document)
.. toctree::
:maxdepth: 2
:numbered:
part1/chapter1
part1/chapter2
part2/chapter3
# part1/chapter1.rst
Part 1, Chapter 1 Title
=======================
Section 1.1
-----------
This is the first section of chapter 1.
Section 1.2
-----------
This is the second section of chapter 1.
# part2/chapter3.rst
Part 2, Chapter 3 Title
=======================
Section 3.1
-----------
This is the first section of chapter 3.
Section 3.2
-----------
This is the second section of chapter 3.
Debug
Known issues
gotchaThe `sphinx-multitoc-numbering` extension is noted as being in an active development stage, implying that its behavior and internal implementation might change rapidly between minor versions.fixUsers should regularly check the official documentation and GitHub repository for updates and potential breaking changes when upgrading or relying on specific behaviors.
affects: All versions up to 0.1.3
gotchaWhen running Sphinx builds in parallel (e.g., with `sphinx-build -j auto`), the extension may issue a warning stating that it is not safe for parallel builds. This indicates potential race conditions or incorrect state handling during concurrent processing.fixTo avoid potential issues or warnings, consider running Sphinx builds in a single-job mode (without `-j` or with `-j 1`). If parallel builds are necessary, monitor the build logs carefully for any unexpected numbering or build failures.
affects: All versions up to 0.1.3 (as per open issue #27)
gotchaSphinx's incremental build process can sometimes lead to caching issues where numbering updates from `sphinx-multitoc-numbering` are not correctly applied, resulting in 'weird numbering' or outdated results in local HTML builds.fixIf you encounter unexpected numbering, perform a clean build by running `make clean html` (or `sphinx-build -b html -aE . _build/html` if not using a Makefile) to force Sphinx to regenerate all output from scratch.
affects: All versions up to 0.1.3
Upgrade
Version history
0.1.3latest on PyPI · released Mar 15, 2021
Audit
Dependencies
No dependency data recorded yet.