Advanced section numbering customization #112
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Introduced a logger and added a warning message when initializing the sphinx_external_toc extension to indicate it is a forked version. This helps with debugging and tracking extension usage.
Introduces a new collectors.py module with a custom TocTreeCollectorWithAppendices and a function to disable the built-in TocTreeCollector. Updates the extension setup to use these changes, ensuring the custom collector is registered and the built-in one is disabled, with logging for both actions.
Introduces a 'style' attribute to the TocTree class for specifying toctree rendering style (e.g., numerical, roman, letter). The style is validated and passed through to the generated node in the insert_toctrees event.
Modified the validator lambda for the 'style' attribute in the TocTree class to accept three arguments instead of one, aligning with expected usage.
Introduces a 'style' option to TOCTREE_OPTIONS and adds a validator to ensure only allowed style values are accepted. Updates the TocTree dataclass to use the new validate_style function for style validation.
Renames the custom collector class to TocTreeCollectorWithStyles and updates its usage in the extension setup. Adds a process_doc method stub for future style processing, with logging for debugging.
The 'toctree' import from docutils.nodes was not used in the file and has been removed to clean up the imports.
Replaces the process_doc override with assign_section_numbers in TocTreeCollectorWithStyles. This change ensures custom style processing occurs after section numbers are assigned, maintaining original behavior and logging.
Added a loop to log each docname in env.numbered_toctrees and retrieve its doctree for additional processing. This enhances visibility into which documents are being processed during style handling.
Enhanced TocTreeCollectorWithStyles to log each found toctree node within doctrees for debugging and analysis purposes.
Added a check to log a warning when a toctree with a style other than 'numerical' is found during document processing. This helps identify and debug custom toctree styles in the documentation.
The warning now includes the toctree caption (or 'NAMELESS' if missing) along with the non-numerical style, providing more context for debugging.
Introduces a private __renumber method to handle section number style conversion in TocTreeCollectorWithStyles. Currently, the method returns the original number unless a specific style is provided.
Implemented conversion of TOC numbering to upper and lower case Roman numerals in TocTreeCollectorWithStyles. Added a helper method to convert integers to Roman numerals and updated renumbering logic to handle 'romanupper' and 'romanlower' styles.
Introduces support for 'alphaupper' and 'alphalower' section numbering styles in TocTreeCollectorWithStyles by adding counters and a method to convert integers to alphabetical representations.
Added a counter for the 'numerical' style and updated the renumbering logic to handle all styles, including 'numerical', consistently. This ensures section numbers are properly converted based on the specified style in toctree entries.
Introduces a __replace_toc method to recursively update section numbers in the table of contents according to a specified style. This ensures that section numbers in the TOC reflect the desired numbering format, and raises an error if nested toctrees are encountered.
The RuntimeError for nested toctrees has been commented out in TocTreeCollectorWithStyles. This may allow nested toctrees to be processed or ignored without raising an exception.
Moves the increment of section number counters for different styles from __renumber to the main loop in TocTreeCollectorWithStyles. This avoids double-incrementing and ensures counters are updated only once per entry.
Introduces a __version__ variable set to '1.1.0-dev' and updates the setup() function to return the extension version in its metadata dictionary.
Clarified Jupyter Book extension usage and configuration details.
Update README with Jupyter Book configuration info
Refines the behavior of the `restart_numbering` option for ToC subtrees, making its default value depend on the `use_multitoc_numbering` setting. Updates the README to clarify the new logic and usage, changes the API to allow `restart_numbering` to be None, and adjusts the collector logic to apply the correct default based on configuration.
Deleted warning and note sections regarding the use of the 'numbered' option and title numbering behavior in the Sphinx user guide. This streamlines the documentation and removes potentially confusing or redundant information.
Replaces use of env.app.config.get with direct attribute access for 'use_multitoc_numbering'. This ensures correct retrieval of the configuration value and avoids defaulting to True if the option is missing.
Patch multitoc
Enhances the assign_section_numbers method to more robustly map and update section numbers in env.toc_secnumbers, ensuring consistency after style changes. The update includes storing old titles, handling renumbering logic for anchors, and converting section numbers to tuples to maintain compatibility with other parts of the algorithm.
Eliminated the unused __map_old_to_new dictionary and related code from TocTreeCollectorWithStyles. This simplifies the class by removing unnecessary state and logic.
Eliminated the unused 'count' and 'old_secnumber' variables from the TocTreeCollectorWithStyles class to clean up the code and improve readability.
Improve section number mapping in TOC collector
Tom-van-Woudenberg
force-pushed
the
main
branch
from
8ae19b9 to
fd4b7dc
Compare
This commit applies consistent code formatting across multiple files, including breaking up long lines, improving indentation, and expanding function arguments for better readability. No functional changes are introduced; the modifications are solely for code clarity and maintainability.
Added 'style' and 'restart_numbering' fields to toctree structures in YAML and XML test files to support new features. Updated TocTreeCollectorWithStyles to skip non-internal document references when fixing nested toctrees. This improves handling of toctree options and ensures correct processing of document references.
Updated the _strip_ignores method to convert 0/1 to False/True for specific attributes, ensuring consistent test output across platforms.
Consolidated multi-line statements into single lines across multiple files to enhance code readability and maintain consistency. No functional changes were made.
Author
|
The failing tests are because of a rate limit for CodeCov, the tests themselves do not fail. |
FreekPols
reviewed
Jan 14, 2026
Deleted the note about this being a forked version with custom section numbering features. The README now focuses on the general description of the extension.
FreekPols
approved these changes
Jan 14, 2026
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This pull request introduces section numbering styles and improved numbering control to the
sphinx-external-tocextension, making it possible to customize section numbers (numerical, roman, alphabetic, etc.) and restart numbering per subtree. It also integrates thesphinx-multitoc-numberingextension 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
numerical,romanupper,romanlower,alphaupper,alphalower) and the ability to restart numbering per subtree via newstyleandrestart_numberingoptions in the ToC configuration. [1] [2] [3] [4] [5] [6] [7] [8]TocTreedataclass. [1] [2]Integration and Collector Changes
sphinx-multitoc-numberingas a dependency and initialized it in the extension setup. [1] [2]TocTreeCollectorWithStyles) that applies the new numbering styles and logic. [1] [2]Documentation Updates
README.mdand 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
1.1.0-devto reflect these major enhancements.