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 the __fix_nested_toc method to process nested toctrees instead of raising a RuntimeError. This change updates section numbers and recursively replaces tocs for nested entries, improving support for complex toctree structures.
Introduces a new 'restart_numbering' boolean field to the TocTree class and includes it in the list of recognized TOCTREE_OPTIONS. This allows users to specify whether numbering should restart for a given toctree style.
Introduces handling of a 'restart_numbering' attribute in toctree nodes. When set, the section numbering for the specified style is reset, and a warning is logged. This allows for more flexible control over section numbering in generated documentation.
Updated the TocTree style attribute to accept both string and list values, adjusting validation and internal handling accordingly. This allows for more flexible style specifications in toctree rendering and ensures correct processing when multiple styles are provided.
Enhanced the logic in TocTreeCollectorWithStyles to convert each number in number_set to its corresponding style in style_set, rather than only converting the first. This allows for more flexible and accurate handling of mixed numbering styles in toctrees.
Added explicit type checks for numerical and string values in the renumbering loop to prevent incorrect conversions and ensure only appropriate types are processed.
Eliminated all logger.warning debug statements from the TocTreeCollectorWithStyles class and related functions to clean up the code and reduce unnecessary log output.
Documents new options for defining section numbering styles and restarting numbering per subtree in the Table of Contents. Adds details and examples for the 'style' and 'restart_numbering' options, and updates usage instructions accordingly.
Added a check to ensure 'secnumber' exists in env.titles[ref] before processing section numbers in TocTreeCollectorWithStyles. This prevents errors when entries do not have a 'secnumber' attribute. Also, setup now loads 'sphinx_multitoc_numbering' extension.
Clarifies section numbering features, adds note about automatic inclusion of `sphinx-multitoc-numbering`, and explains that `use_multitoc_numbering: false` is ignored in JupyterBooks.
Eliminated the import and usage of the logger in sphinx_external_toc/__init__.py as it was not being used except for a warning message, which has also been removed.
Clarifies documentation for section numbering options and subtree configuration in README. Removes unused __version__ variable from __init__.py. Adds checks in collectors.py to handle missing or empty section numbers, preventing potential errors during section renumbering.
Included 'sphinx-multitoc-numbering>=0.1.3' in the project dependencies to support multi-TOC numbering in Sphinx documentation builds.
Introduces a __version__ variable set to '1.1.0-dev' and updates the setup() function to return the extension version in its metadata dictionary.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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 advanced section numbering customization to the forked
sphinx-external-tocextension. It adds support for per-subtree section numbering styles (numerical, roman, alphabetic, etc.), the ability to restart numbering per subtree, and enforces continuous section numbering across multiple toctrees by integratingsphinx-multitoc-numbering. The documentation and codebase have been updated to reflect these new features, and the extension disables the built-in Sphinx toctree collector to ensure correct behavior.New section numbering features:
Added
styleandrestart_numberingoptions to the ToC YAML schema and theTocTreeAPI, allowing users to specify section numbering style (numerical, romanupper, romanlower, alphaupper, alphalower) and whether numbering restarts per subtree. These are validated and documented in both the code andREADME.md. [1] [2] [3] [4] [5] [6] [7] [8]Implemented a custom
TocTreeCollectorWithStylesclass that overrides Sphinx's default collector to apply the new numbering styles and restart logic, including conversion functions for roman and alphabetic numbering.Integration and dependencies:
Automatically includes and enforces
sphinx-multitoc-numberingas a dependency, ensuring continuous section numbering across multiple toctrees. The extension now ignores theuse_multitoc_numbering: falsesetting in JupyterBooks. [1] [2] [3] [4]Disables the built-in Sphinx toctree collector and registers the custom collector to prevent conflicts and ensure correct section numbering.
Documentation updates:
README.mdwith detailed explanations and examples of the newstyleandrestart_numberingoptions, updated warnings and notes, and clarified how the new features replace some previous workarounds. [1] [2] [3] [4] [5] [6]Versioning:
1.1.0-devto reflect these significant new features.YAML and event handling:
These changes collectively provide users with much more flexibility and control over section numbering in Sphinx projects, especially when using external ToC files.