Sphinx Multitoc Numbering

0.1.3 · active · verified Thu Apr 16

Sphinx Multitoc Numbering is a Sphinx extension designed to provide continuous section numbering across multiple table-of-contents (toctrees) within HTML output. It's particularly useful for projects like Jupyter Book that combine various documents into a cohesive structure, ensuring a unified numbering scheme. The current version is 0.1.3, released on March 15, 2021, and the project documentation indicates it is in an active development stage, though its release cadence is infrequent.

Common errors

```
WARNING: <extension> is not safe for parallel builds
```
cause The `sphinx-multitoc-numbering` extension might not handle parallel build environments correctly, leading to this warning.

fix Run your Sphinx build without the parallel jobs option (e.g., `sphinx-build -b html . _build/html` instead of `sphinx-build -j auto ...`).
```
Chapters are incorrectly numbered based on lexicographical ordering of the book part file names (Jupyter Book)
```
cause This is a known bug where the extension, particularly in Jupyter Book projects, may order and number chapters based on filename alphabetical order rather than the logical order defined in `_toc.yml` or RST `toctree` directives.

fix Verify that your `_toc.yml` or RST `toctree` definitions correctly specify the desired order. As a workaround, ensure file names are prefixed numerically (e.g., `01_intro.rst`, `02_chapter.rst`) to align lexicographical with logical order, or perform a `make clean html` to refresh the build.
```
Wrong chapter numbers when toctrees located in different .rst files
```
cause This issue occurs when a top-level unnumbered toctree includes multiple files, each containing their own numbered toctrees, leading to inconsistent or incorrect chapter numbering.

fix Ensure that your primary `toctree` in the master document (e.g., `index.rst`) is the one defining `:numbered:`. Sub-toctrees typically do not need their own `:numbered:` option if the parent toctree is intended to drive the overall numbering. A clean build (`make clean html`) can often resolve lingering issues.

Warnings

gotcha The `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.
Fix: Users should regularly check the official documentation and GitHub repository for updates and potential breaking changes when upgrading or relying on specific behaviors.
gotcha When 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.
Fix: To 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.
gotcha Sphinx'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.
Fix: If 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.

Install

pip install sphinx-multitoc-numbering Install latest version

Imports

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.

Quickstart

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.

view raw JSON →