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.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 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.