{"id":8674,"library":"sphinx-multitoc-numbering","title":"Sphinx Multitoc Numbering","description":"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.","status":"active","version":"0.1.3","language":"en","source_language":"en","source_url":"https://github.com/executablebooks/sphinx-multitoc-numbering","tags":["Sphinx","documentation","extension","numbering","HTML","Jupyter Book","toctree"],"install":[{"cmd":"pip install sphinx-multitoc-numbering","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"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.","symbol":"sphinx_multitoc_numbering","correct":"extensions = [\n    \"sphinx.ext.autodoc\",\n    \"sphinx_multitoc_numbering\"\n]"}],"quickstart":{"code":"# conf.py\n# ...\nproject = 'My Multi-Part Documentation'\ncopyright = '2024, Your Name'\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx_multitoc_numbering'\n]\n# ...\n\n# index.rst (or your master document)\n.. toctree::\n   :maxdepth: 2\n   :numbered:\n\n   part1/chapter1\n   part1/chapter2\n   part2/chapter3\n\n\n# part1/chapter1.rst\nPart 1, Chapter 1 Title\n=======================\n\nSection 1.1\n-----------\n\nThis is the first section of chapter 1.\n\nSection 1.2\n-----------\n\nThis is the second section of chapter 1.\n\n\n# part2/chapter3.rst\nPart 2, Chapter 3 Title\n=======================\n\nSection 3.1\n-----------\n\nThis is the first section of chapter 3.\n\nSection 3.2\n-----------\n\nThis is the second section of chapter 3.\n","lang":"python","description":"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."},"warnings":[{"fix":"Users should regularly check the official documentation and GitHub repository for updates and potential breaking changes when upgrading or relying on specific behaviors.","message":"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.","severity":"gotcha","affected_versions":"All versions up to 0.1.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions up to 0.1.3 (as per open issue #27)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions up to 0.1.3"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run your Sphinx build without the parallel jobs option (e.g., `sphinx-build -b html . _build/html` instead of `sphinx-build -j auto ...`).","cause":"The `sphinx-multitoc-numbering` extension might not handle parallel build environments correctly, leading to this warning.","error":"WARNING: <extension> is not safe for parallel builds"},{"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.","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.","error":"Chapters are incorrectly numbered based on lexicographical ordering of the book part file names (Jupyter Book)"},{"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.","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.","error":"Wrong chapter numbers when toctrees located in different .rst files"}]}