sphinx-external-toc icon indicating copy to clipboard operation
sphinx-external-toc copied to clipboard

Advanced section numbering customization

Open douden opened this issue 3 months ago • 0 comments

This pull request 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.

Section Numbering Styles and Restart Control

  • Added support for customizable section numbering styles (numerical, romanupper, romanlower, alphaupper, alphalower) and the ability to restart numbering per subtree via new style and restart_numbering options in the ToC configuration. [1] [2] [3] [4] [5] [6] [7] [8]
  • Implemented validation for allowed numbering styles and added corresponding fields to the TocTree dataclass. [1] [2]

Integration and Collector Changes

  • Integrated sphinx-multitoc-numbering as a dependency and initialized it in the extension setup. [1] [2]
  • Disabled the built-in Sphinx toctree collector and replaced it with a custom collector (TocTreeCollectorWithStyles) that applies the new numbering styles and logic. [1] [2]

Documentation Updates

  • Updated the README.md and user guide to document the new features, configuration options, and clarify the default behaviors for Jupyter Book users. Deprecated references to the old multitoc-numbering extension and clarified numbering behavior. [1] [2] [3]

Versioning

  • Bumped the extension version to 1.1.0-dev to reflect these major enhancements.

douden avatar Oct 16 '25 10:10 douden