Advanced section numbering customization (#112)

This merge commit introduces section numbering styles and improved numbering control to the sphinx-external-toc extension, making it possible to customize section numbers (numerical, roman, alphabetic, etc.) and restart numbering per subtree. It also integrates the sphinx-multitoc-numbering extension directly, disables the built-in Sphinx toctree collector, and adds support for new configuration options. The documentation and codebase have been updated to reflect these enhancements.

Author: douden

.github/workflows/tests.yml

@@ -18,10 +18,12 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9","3.10", "3.11", "3.12", "3.13","3.14"]
         include:
         - os: windows-latest
-          python-version: 3.9
+          python-version: "3.9"
+        - os: windows-latest
+          python-version: "3.14"
 
     runs-on: ${{ matrix.os }}
 
@@ -39,13 +41,13 @@ jobs:
       run: |
         pytest --cov=sphinx_external_toc --cov-report=xml --cov-report=term-missing
     - name: Upload to Codecov
-      if: matrix.python-version == 3.11
-      uses: codecov/codecov-action@v3
+      if: matrix.python-version == '3.14'
+      uses: codecov/codecov-action@v4
       with:
-        name: pytests-py3.11
+        name: pytests-py3.14
         flags: pytests
         file: ./coverage.xml
-        fail_ci_if_error: true
+        fail_ci_if_error: false # uploading coverage should not fail the tests
 
   publish:
 

.readthedocs.yml

@@ -15,3 +15,4 @@ python:
 sphinx:
   builder: html
   fail_on_warning: true
+  configuration: docs/conf.py

README.md

@@ -6,7 +6,7 @@
 [![PyPI][pypi-badge]][pypi-link]
 
 A sphinx extension that allows the documentation site-map (a.k.a Table of Contents) to be defined external to the documentation files.
-As used by [Jupyter Book](https://jupyterbook.org)!
+As used by default by [Jupyter Book](https://jupyterbook.org) (no need to manually add this extension to the extensions in `_config.yml` in a JupyterBook)!
 
 In normal Sphinx documentation, the documentation site-map is defined *via* a bottom-up approach - adding [`toctree` directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents) within pages of the documentation.
 
@@ -24,12 +24,25 @@ Add to your `conf.py`:
 
 ```python
 extensions = ["sphinx_external_toc"]
+use_multitoc_numbering = True  # optional, default: True
 external_toc_path = "_toc.yml"  # optional, default: _toc.yml
 external_toc_exclude_missing = False  # optional, default: False
 ```
 
 Note the `external_toc_path` is always read as a Unix path, and can either be specified relative to the source directory (recommended) or as an absolute path.
 
+### Jupyterbook configuration
+
+This extension is included in your jupyterbook configuration by default, so there's need to add it to the list of extensions. The other options can still be added:
+
+```yaml
+use_multitoc_numbering: true  # optional, default: true
+external_toc_path: "_toc.yml"  # optional, default: _toc.yml
+external_toc_exclude_missing: False  # optional, default: False
+```
+
+Note the `external_toc_path` is always read as a Unix path, and can either be specified relative to the source directory (recommended) or as an absolute path.
+
 ### Basic Structure
 
 A minimal ToC defines the top level `root` key, for a single root document file:
@@ -113,11 +126,27 @@ Each subtree can be configured with a number of options (see also [sphinx `toctr
   By default it is appended to the end of the document, but see also the `tableofcontents` directive for positioning of the ToC.
 - `maxdepth` (integer): A maximum nesting depth to use when showing the ToC within the document (default -1, meaning infinite).
 - `numbered` (boolean or integer): Automatically add numbers to all documents within a subtree (default `False`).
-  If set to `True`, all sub-trees will also be numbered based on nesting (e.g. with `1.1` or `1.1.1`),
-  or if set to an integer then the numbering will only be applied to that depth.
+  If set to `True`, all subtrees will also be numbered based on nesting (e.g. with `1.1` or `1.1.1`),
+  or if set to an integer then the numbering will only be applied until that depth. Warning: This can lead to unexpected results if not carefully managed, for example references created using `numref` may fail. Internally this options is always converted to an integer, with `True` -> `999` (effectively unlimited depth) and `False` -> `0` (no numbering).
 - `reversed` (boolean): If `True` then the entries in the subtree will be listed in reverse order (default `False`).
   This can be useful when using `glob` entries.
 - `titlesonly` (boolean): If `True` then only the first heading in the document will be shown in the ToC, not other headings of the same level (default `False`).
+- `style` (string or list of strings): The section numbering style to use for this subtree (default `numerical`).
+  If a single string is given, this will be used for the top level of the subtree.
+  If a list of strings is given, then each entry will be used for the corresponding level of section numbering.
+  If styles are not given for all levels, then the remaining levels will be `numerical`.
+  If too many styles are given, the extra ones will be ignored.
+  The first time a style is used at the top level in a subtree, the numbering will start from 1, 'a', 'A', 'I' or 'i' depending on the style.
+  Subsequent times the same style is used at the top level in a subtree, the numbering will continue from the last number used for that style, unless `restart_numbering` is set to `True`.
+  Available styles:
+  - `numerical`: 1, 2, 3, ...
+  - `romanlower`: i, ii, iii, iv, v, ...
+  - `romanupper`: I, II, III, IV, V, ...
+  - `alphalower`: a, b, c, d, e, ..., aa, ab, ...
+  - `alphaupper`: A, B, C, D, E, ..., AA, AB, ...
+- `restart_numbering` (boolean): If `True`, the numbering for the top level of this subtree will restart from 1 (or 'a', 'A', 'I' or 'i' depending on the style). If `False` the numbering for the top level of this subtree will continue from the last letter/number/symbol used in a previous subtree with the same style. The default value of this option is `not use_multitoc_numbering`. This means that:
+  - if `use_multitoc_numbering` is `True` (the default), the numbering for each part will continue from the last letter/number/symbol used in a previous part with the same style, unless `restart_numbering` is explicitly set to `True`.
+  - if `use_multitoc_numbering` is `False`, the numbering of each subtree will restart from 1 (or 'a', 'A', 'I' or 'i' depending on the style), unless `restart_numbering` is explicitly set to `False`.
 
 These options can be set at the level of the subtree:
 
@@ -130,6 +159,8 @@ subtrees:
   numbered: True
   reversed: False
   titlesonly: True
+  style: [alphaupper, romanlower]
+  restart_numbering: True
   entries:
   - file: doc1
     subtrees:
@@ -149,6 +180,8 @@ options:
   numbered: True
   reversed: False
   titlesonly: True
+  style: [alphaupper, romanlower]
+  restart_numbering: True
 entries:
 - file: doc1
   options:
@@ -169,21 +202,14 @@ options:
   maxdepth: 1
   numbered: True
   reversed: False
+  style: [alphaupper, romanlower]
+  restart_numbering: True
 entries:
 - file: doc1
   entries:
   - file: doc2
 ```
 
-:::{warning}
-`numbered` should not generally be used as a default, since numbering cannot be changed by nested subtrees, and sphinx will log a warning.
-:::
-
-:::{note}
-By default, title numbering restarts for each subtree.
-If you want want this numbering to be continuous, check-out the [sphinx-multitoc-numbering extension](https://github.com/executablebooks/sphinx-multitoc-numbering).
-:::
-
 ### Using different key-mappings
 
 For certain use-cases, it is helpful to map the `subtrees`/`entries` keys to mirror e.g. an output [LaTeX structure](https://www.overleaf.com/learn/latex/sections_and_chapters).
@@ -424,13 +450,13 @@ meta: {}
 
 Questions / TODOs:
 
-- Add additional top-level keys, e.g. `appendices` (see https://github.com/sphinx-doc/sphinx/issues/2502) and `bibliography`
+- ~~Add additional top-level keys, e.g. `appendices` (see https://github.com/sphinx-doc/sphinx/issues/2502) and `bibliography`.~~ Can be replaced by setting the numbering style and (possibly) restarting the numbering.
 - Using `external_toc_exclude_missing` to exclude a certain file suffix:
   currently if you had files `doc.md` and `doc.rst`, and put `doc.md` in your ToC,
   it will add `doc.rst` to the excluded patterns but then, when looking for `doc.md`,
   will still select `doc.rst` (since it is first in `source_suffix`).
   Maybe open an issue on sphinx, that `doc2path` should respect exclude patterns.
-- Integrate https://github.com/executablebooks/sphinx-multitoc-numbering into this extension? (or upstream PR)
+- ~~Integrate https://github.com/executablebooks/sphinx-multitoc-numbering into this extension? (or upstream PR).~~ Included and enforced in this fork.
 - document suppressing warnings
 - test against orphan file
 - https://github.com/executablebooks/sphinx-book-theme/pull/304

docs/user_guide/sphinx.md

@@ -6,6 +6,7 @@ Add to your `conf.py`:
 
 ```python
 extensions = ["sphinx_external_toc"]
+use_multitoc_numbering = True  # optional, default: True
 external_toc_path = "_toc.yml"  # optional, default: _toc.yml
 external_toc_exclude_missing = False  # optional, default: False
 ```
@@ -95,11 +96,27 @@ Each subtree can be configured with a number of options (see also [sphinx `toctr
   By default it is appended to the end of the document, but see also the `tableofcontents` directive for positioning of the ToC.
 - `maxdepth` (integer): A maximum nesting depth to use when showing the ToC within the document (default -1, meaning infinite).
 - `numbered` (boolean or integer): Automatically add numbers to all documents within a subtree (default `False`).
-  If set to `True`, all sub-trees will also be numbered based on nesting (e.g. with `1.1` or `1.1.1`),
+  If set to `True`, all subtrees will also be numbered based on nesting (e.g. with `1.1` or `1.1.1`),
   or if set to an integer then the numbering will only be applied to that depth.
 - `reversed` (boolean): If `True` then the entries in the subtree will be listed in reverse order (default `False`).
   This can be useful when using `glob` entries.
 - `titlesonly` (boolean): If `True` then only the first heading in the document will be shown in the ToC, not other headings of the same level (default `False`).
+- `style` (string or list of strings): The section numbering style to use for this subtree (default `numerical`).
+  If a single string is given, this will be used for the top level of the subtree.
+  If a list of strings is given, then each entry will be used for the corresponding level of section numbering.
+  If styles are not given for all levels, then the remaining levels will be `numerical`.
+  If too many styles are given, the extra ones will be ignored.
+  The first time a style is used at the top level in a subtree, the numbering will start from 1, 'a', 'A', 'I' or 'i' depending on the style.
+  Subsequent times the same style is used at the top level in a subtree, the numbering will continue from the last number used for that style, unless `restart_numbering` is set to `True`.
+  Available styles:
+  - `numerical`: 1, 2, 3, ...
+  - `romanlower`: i, ii, iii, iv, v, ...
+  - `romanupper`: I, II, III, IV, V, ...
+  - `alphalower`: a, b, c, d, e, ..., aa, ab, ...
+  - `alphaupper`: A, B, C, D, E, ..., AA, AB, ...
+- `restart_numbering` (boolean): If `True`, the numbering for the top level of this subtree will restart from 1 (or 'a', 'A', 'I' or 'i' depending on the style). If `False` the numbering for the top level of this subtree will continue from the last letter/number/symbol used in a previous subtree with the same style. The default value of this option is `not use_multitoc_numbering`. This means that:
+  - if `use_multitoc_numbering` is `True` (the default), the numbering for each part will continue from the last letter/number/symbol used in a previous part with the same style, unless `restart_numbering` is explicitly set to `True`.
+  - if `use_multitoc_numbering` is `False`, the numbering of each subtree will restart from 1 (or 'a', 'A', 'I' or 'i' depending on the style), unless `restart_numbering` is explicitly set to `False`.
 
 These options can be set at the level of the subtree:
 
@@ -112,6 +129,8 @@ subtrees:
   numbered: True
   reversed: False
   titlesonly: True
+  style: [alphaupper, romanlower]
+  restart_numbering: True
   entries:
   - file: doc1
     subtrees:
@@ -131,6 +150,8 @@ options:
   numbered: True
   reversed: False
   titlesonly: True
+  style: [alphaupper, romanlower]
+  restart_numbering: True
 entries:
 - file: doc1
   options:
@@ -151,21 +172,14 @@ options:
   maxdepth: 1
   numbered: True
   reversed: False
+  style: [alphaupper, romanlower]
+  restart_numbering: True
 entries:
 - file: doc1
   entries:
   - file: doc2
 ```
 
-:::{warning}
-`numbered` should not generally be used as a default, since numbering cannot be changed by nested subtrees, and sphinx will log a warning.
-:::
-
-:::{note}
-By default, title numbering restarts for each subtree.
-If you want want this numbering to be continuous, check-out the [sphinx-multitoc-numbering extension](https://github.com/executablebooks/sphinx-multitoc-numbering).
-:::
-
 ## Using different key-mappings
 
 For certain use-cases, it is helpful to map the `subtrees`/`entries` keys to mirror e.g. an output [LaTeX structure](https://www.overleaf.com/learn/latex/sections_and_chapters).

pyproject.toml

@@ -29,6 +29,7 @@ dependencies = [
     "click>=7.1",
     "pyyaml",
     "sphinx>=5",
+    "sphinx-multitoc-numbering>=0.1.3"
 ]
 
 [project.urls]

sphinx_external_toc/__init__.py

@@ -1,16 +1,21 @@
 """A sphinx extension that allows the project toctree to be defined in a single file."""
 
-__version__ = "1.0.1"
-
-
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
 
+__version__ = "1.1.0-dev"
+
 
 def setup(app: "Sphinx") -> dict:
+    app.setup_extension("sphinx_multitoc_numbering")
+
     """Initialize the Sphinx extension."""
+    from .collectors import (
+        TocTreeCollectorWithStyles,
+        disable_builtin_toctree_collector,
+    )
     from .events import (
         InsertToctrees,
         TableofContents,
@@ -19,10 +24,21 @@ def setup(app: "Sphinx") -> dict:
         parse_toc_to_env,
     )
 
+    # collectors
+    disable_builtin_toctree_collector(app)
+    app.add_env_collector(TocTreeCollectorWithStyles)
+
     # variables
     app.add_config_value("external_toc_path", "_toc.yml", "env")
     app.add_config_value("external_toc_exclude_missing", False, "env")
 
+    # Register use_multitoc_numbering if not already registered (e.g., by JupyterBook)
+    try:
+        app.add_config_value("use_multitoc_numbering", True, "env")
+    except Exception:
+        # Already registered, likely by JupyterBook
+        pass
+
     # Note: this needs to occur after merge_source_suffix event (priority 800)
     # this cannot be a builder-inited event, since if we change the master_doc
     # it will always mark the config as changed in the env setup and re-build everything

sphinx_external_toc/_compat.py

@@ -1,4 +1,5 @@
 """Compatibility for using dataclasses instead of attrs."""
+
 from __future__ import annotations
 
 import dataclasses as dc
@@ -121,7 +122,8 @@ def _validator(inst, attr, value):
 
 
 def deep_iterable(
-    member_validator: ValidatorType, iterable_validator: ValidatorType | None = None
+    member_validator: ValidatorType,
+    iterable_validator: ValidatorType | None = None,
 ) -> ValidatorType:
     """
     A validator that performs deep validation of an iterable.
@@ -147,3 +149,21 @@ def findall(node: Element):
     # findall replaces traverse in docutils v0.18
     # note a difference is that findall is an iterator
     return getattr(node, "findall", node.traverse)
+
+
+def validate_style(instance, attribute, value):
+    allowed = [
+        "numerical",
+        "romanupper",
+        "romanlower",
+        "alphaupper",
+        "alphalower",
+    ]
+    if isinstance(value, list):
+        for v in value:
+            if v not in allowed:
+                raise ValueError(
+                    f"{attribute.name} must be one of {allowed}, not {v!r}"
+                )
+    elif value not in allowed:
+        raise ValueError(f"{attribute.name} must be one of {allowed}, not {value!r}")

sphinx_external_toc/api.py

@@ -1,4 +1,5 @@
 """Defines the `SiteMap` object, for storing the parsed ToC."""
+
 from collections.abc import MutableMapping
 from dataclasses import asdict, dataclass
 from typing import Any, Dict, Iterator, List, Optional, Set, Union
@@ -11,6 +12,7 @@
     matches_re,
     optional,
     validate_fields,
+    validate_style,
 )
 
 #: Pattern used to match URL items.
@@ -61,6 +63,15 @@ class TocTree:
     )
     reversed: bool = field(default=False, kw_only=True, validator=instance_of(bool))
     titlesonly: bool = field(default=False, kw_only=True, validator=instance_of(bool))
+    # Add extra field for style of toctree rendering
+    style: Union[List[str], str] = field(
+        default="numerical", kw_only=True, validator=validate_style
+    )
+    # add extra field for restarting numbering for the set style
+    # Only allow True, False or None. None is the default value.
+    restart_numbering: Optional[bool] = field(
+        default=None, kw_only=True, validator=optional(instance_of(bool))
+    )
 
     def __post_init__(self):
         validate_fields(self)
@@ -213,9 +224,11 @@ def _replace_items(d: Dict[str, Any]) -> Dict[str, Any]:
                     d[k] = _replace_items(v)
                 elif isinstance(v, (list, tuple)):
                     d[k] = [
-                        _replace_items(i)
-                        if isinstance(i, dict)
-                        else (str(i) if isinstance(i, str) else i)
+                        (
+                            _replace_items(i)
+                            if isinstance(i, dict)
+                            else (str(i) if isinstance(i, str) else i)
+                        )
                         for i in v
                     ]
                 elif isinstance(v, str):