Advanced section numbering customization #112
Merged
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.
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.
Contributor
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
previously approved these changes
Jan 14, 2026
Added Python 3.13 and 3.14 to the test matrix and updated Codecov upload to run on Python 3.14 with the latest action version. Coverage upload is now non-blocking for CI.
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #112 +/- ##
==========================================
- Coverage 90.83% 90.28% -0.55%
==========================================
Files 7 8 +1
Lines 742 937 +195
==========================================
+ Hits 674 846 +172
- Misses 68 91 +23
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Introduce unit tests for TocTreeCollectorWithStyles and disable_builtin_toctree_collector functions. Tests cover Roman numeral and alphabetical conversions, renumbering logic, and disabling behavior for collectors.
Added Python 3.9 to the GitHub Actions test matrix for both Ubuntu and Windows environments. Refactored test code in conftest.py and test_collectors.py for better readability and consistency, including improved argument formatting and removal of unused imports.
Split Windows test matrix to run Python 3.9 and 3.14 separately instead of as a range. This ensures tests are executed for both versions individually.
Added comprehensive unit tests for TocTreeCollectorWithStyles, covering edge cases, all numbering styles, and internal methods. Refactored test setup for better coverage and removed unnecessary patching. Also fixed import order in collectors.py for consistency.
Added a comprehensive test suite for the sphinx_external_toc._compat module in tests/test_compat.py, covering validators, dataclass utilities, conditional imports, and type annotations. Also removed unused imports and cleaned up some test logic in tests/test_collectors.py.
Introduces new test files and fixtures for TOC parsing, site creation, and migration commands. Adds comprehensive coverage for _compat.py, including edge cases and error handling. Provides sample TOC files and expected outputs for regression and parsing tests.
Improved readability in test_cli.py by reformatting long import and function call lines. Removed unused imports in test_compat.py to clean up the test code.
Ensures the CLI is invoked in test_migrate_toc_with_output_file before asserting the output file's existence and contents.
Updated assert statements in test_collectors.py to use a more readable multi-line format, improving code clarity in test failure messages.
FreekPols
approved these changes
Jan 15, 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.