Reformat code for improved readability and consistency

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.

Author: douden

sphinx_external_toc/__init__.py

@@ -12,17 +12,17 @@ def setup(app: "Sphinx") -> dict:
     app.setup_extension("sphinx_multitoc_numbering")
 
     """Initialize the Sphinx extension."""
+    from .collectors import (
+        TocTreeCollectorWithStyles,
+        disable_builtin_toctree_collector,
+    )
     from .events import (
         InsertToctrees,
         TableofContents,
         add_changed_toctrees,
         ensure_index_file,
         parse_toc_to_env,
     )
-    from .collectors import (
-        disable_builtin_toctree_collector,
-        TocTreeCollectorWithStyles,
-    )
 
     # collectors
     disable_builtin_toctree_collector(app)

sphinx_external_toc/_compat.py

@@ -1,4 +1,5 @@
 """Compatibility for using dataclasses instead of attrs."""
+
 from __future__ import annotations
 
 import dataclasses as dc
@@ -18,7 +19,9 @@ def field(**kwargs: Any):
     if sys.version_info < (3, 10):
         kwargs.pop("kw_only", None)
     if "validator" in kwargs:
-        kwargs.setdefault("metadata", {})["validator"] = kwargs.pop("validator")
+        kwargs.setdefault("metadata", {})["validator"] = kwargs.pop(
+            "validator"
+        )
     return dc.field(**kwargs)
 
 
@@ -92,7 +95,9 @@ def matches_re(regex: str | Pattern, flags: int = 0) -> ValidatorType:
     if fullmatch:
         match_func = pattern.fullmatch
     else:  # Python 2 fullmatch emulation (https://bugs.python.org/issue16203)
-        pattern = re.compile(r"(?:{})\Z".format(pattern.pattern), pattern.flags)
+        pattern = re.compile(
+            r"(?:{})\Z".format(pattern.pattern), pattern.flags
+        )
         match_func = pattern.match
 
     def _validator(inst, attr, value):
@@ -121,7 +126,8 @@ def _validator(inst, attr, value):
 
 
 def deep_iterable(
-    member_validator: ValidatorType, iterable_validator: ValidatorType | None = None
+    member_validator: ValidatorType,
+    iterable_validator: ValidatorType | None = None,
 ) -> ValidatorType:
     """
     A validator that performs deep validation of an iterable.
@@ -150,12 +156,20 @@ def findall(node: Element):
 
 
 def validate_style(instance, attribute, value):
-    allowed = ["numerical", "romanupper", "romanlower", "alphaupper", "alphalower"]
+    allowed = [
+        "numerical",
+        "romanupper",
+        "romanlower",
+        "alphaupper",
+        "alphalower",
+    ]
     if isinstance(value, list):
         for v in value:
             if v not in allowed:
                 raise ValueError(
                     f"{attribute.name} must be one of {allowed}, not {v!r}"
                 )
     elif value not in allowed:
-        raise ValueError(f"{attribute.name} must be one of {allowed}, not {value!r}")
+        raise ValueError(
+            f"{attribute.name} must be one of {allowed}, not {value!r}"
+        )

sphinx_external_toc/api.py

@@ -1,4 +1,5 @@
 """Defines the `SiteMap` object, for storing the parsed ToC."""
+
 from collections.abc import MutableMapping
 from dataclasses import asdict, dataclass
 from typing import Any, Dict, Iterator, List, Optional, Set, Union
@@ -36,7 +37,9 @@ class UrlItem:
 
     # regex should match sphinx.util.url_re
     url: str = field(validator=[instance_of(str), matches_re(URL_PATTERN)])
-    title: Optional[str] = field(default=None, validator=optional(instance_of(str)))
+    title: Optional[str] = field(
+        default=None, validator=optional(instance_of(str))
+    )
 
     def __post_init__(self):
         validate_fields(self)
@@ -55,13 +58,19 @@ class TocTree:
     caption: Optional[str] = field(
         default=None, kw_only=True, validator=optional(instance_of(str))
     )
-    hidden: bool = field(default=True, kw_only=True, validator=instance_of(bool))
+    hidden: bool = field(
+        default=True, kw_only=True, validator=instance_of(bool)
+    )
     maxdepth: int = field(default=-1, kw_only=True, validator=instance_of(int))
     numbered: Union[bool, int] = field(
         default=False, kw_only=True, validator=instance_of((bool, int))
     )
-    reversed: bool = field(default=False, kw_only=True, validator=instance_of(bool))
-    titlesonly: bool = field(default=False, kw_only=True, validator=instance_of(bool))
+    reversed: bool = field(
+        default=False, kw_only=True, validator=instance_of(bool)
+    )
+    titlesonly: bool = field(
+        default=False, kw_only=True, validator=instance_of(bool)
+    )
     # Add extra field for style of toctree rendering
     style: Union[List[str], str] = field(
         default="numerical", kw_only=True, validator=validate_style
@@ -100,7 +109,9 @@ class Document:
         default_factory=list,
         validator=deep_iterable(instance_of(TocTree), instance_of(list)),
     )
-    title: Optional[str] = field(default=None, validator=optional(instance_of(str)))
+    title: Optional[str] = field(
+        default=None, validator=optional(instance_of(str))
+    )
 
     def __post_init__(self):
         validate_fields(self)
@@ -166,7 +177,9 @@ def file_format(self, value: Optional[str]) -> None:
 
     def globs(self) -> Set[str]:
         """Return set of all globs present across all toctrees."""
-        return {glob for item in self._docs.values() for glob in item.child_globs()}
+        return {
+            glob for item in self._docs.values() for glob in item.child_globs()
+        }
 
     def __getitem__(self, docname: str) -> Document:
         """Enable retrieving a document by name using the indexing operator.
@@ -223,9 +236,11 @@ def _replace_items(d: Dict[str, Any]) -> Dict[str, Any]:
                     d[k] = _replace_items(v)
                 elif isinstance(v, (list, tuple)):
                     d[k] = [
-                        _replace_items(i)
-                        if isinstance(i, dict)
-                        else (str(i) if isinstance(i, str) else i)
+                        (
+                            _replace_items(i)
+                            if isinstance(i, dict)
+                            else (str(i) if isinstance(i, str) else i)
+                        )
                         for i in v
                     ]
                 elif isinstance(v, str):

sphinx_external_toc/cli.py

@@ -4,7 +4,11 @@
 import yaml
 
 from sphinx_external_toc import __version__
-from sphinx_external_toc.parsing import FILE_FORMATS, create_toc_dict, parse_toc_yaml
+from sphinx_external_toc.parsing import (
+    FILE_FORMATS,
+    create_toc_dict,
+    parse_toc_yaml,
+)
 from sphinx_external_toc.tools import (
     create_site_from_toc,
     create_site_map_from_path,
@@ -23,7 +27,11 @@ def main():
 def parse_toc(toc_file):
     """Parse a ToC file to a site-map YAML."""
     site_map = parse_toc_yaml(toc_file)
-    click.echo(yaml.dump(site_map.as_json(), sort_keys=False, default_flow_style=False))
+    click.echo(
+        yaml.dump(
+            site_map.as_json(), sort_keys=False, default_flow_style=False
+        )
+    )
 
 
 @main.command("to-project")
@@ -43,11 +51,16 @@ def parse_toc(toc_file):
     show_default=True,
     help="The default file extension to use.",
 )
-@click.option("-o", "--overwrite", is_flag=True, help="Overwrite existing files.")
+@click.option(
+    "-o", "--overwrite", is_flag=True, help="Overwrite existing files."
+)
 def create_site(toc_file, path, extension, overwrite):
     """Create a project directory from a ToC file."""
     create_site_from_toc(
-        toc_file, root_path=path, default_ext="." + extension, overwrite=overwrite
+        toc_file,
+        root_path=path,
+        default_ext="." + extension,
+        overwrite=overwrite,
     )
     # TODO option to add basic conf.py?
     click.secho("SUCCESS!", fg="green")
@@ -94,7 +107,9 @@ def create_site(toc_file, path, extension, overwrite):
     show_default=True,
     help="The key-mappings to use.",
 )
-def create_toc(site_dir, extension, index, skip_match, guess_titles, file_format):
+def create_toc(
+    site_dir, extension, index, skip_match, guess_titles, file_format
+):
     """Create a ToC file from a project directory."""
     site_map = create_site_map_from_path(
         site_dir,
@@ -110,11 +125,19 @@ def create_toc(site_dir, extension, index, skip_match, guess_titles, file_format
                 continue
             filepath = PurePosixPath(docname)
             # use the folder name for index files
-            name = filepath.parent.name if filepath.name == index else filepath.name
+            name = (
+                filepath.parent.name
+                if filepath.name == index
+                else filepath.name
+            )
             # split into words
             words = name.split("_")
             # remove first word if is an integer
-            words = words[1:] if words and all(c.isdigit() for c in words[0]) else words
+            words = (
+                words[1:]
+                if words and all(c.isdigit() for c in words[0])
+                else words
+            )
             site_map[docname].title = " ".join(words).capitalize()
     data = create_toc_dict(site_map)
     click.echo(yaml.dump(data, sort_keys=False, default_flow_style=False))
@@ -131,7 +154,9 @@ def create_toc(site_dir, extension, index, skip_match, guess_titles, file_format
 @click.option(
     "-o",
     "--output",
-    type=click.Path(allow_dash=True, exists=False, file_okay=True, dir_okay=False),
+    type=click.Path(
+        allow_dash=True, exists=False, file_okay=True, dir_okay=False
+    ),
     help="Write to a file path.",
 )
 def migrate_toc(toc_file, format, output):

sphinx_external_toc/collectors.py

@@ -1,8 +1,9 @@
 import copy
-from sphinx.environment.collectors.toctree import TocTreeCollector
 import gc
-from sphinx import addnodes as sphinxnodes
+
 from docutils import nodes
+from sphinx import addnodes as sphinxnodes
+from sphinx.environment.collectors.toctree import TocTreeCollector
 
 
 def disable_builtin_toctree_collector(app):
@@ -31,7 +32,9 @@ def __init__(self, *args, **kwargs):
 
     def assign_section_numbers(self, env):
         # First, call the original assign_section_numbers to get the default behavior
-        result = super().assign_section_numbers(env)  # needed to maintain functionality
+        result = super().assign_section_numbers(
+            env
+        )  # needed to maintain functionality
 
         # store current titles for mapping
         env.titles_old = copy.deepcopy(env.titles)
@@ -79,7 +82,9 @@ def assign_section_numbers(self, env):
                         new_secnumber = self.__renumber(
                             env.titles[ref]["secnumber"], style
                         )
-                        env.titles[ref]["secnumber"] = copy.deepcopy(new_secnumber)
+                        env.titles[ref]["secnumber"] = copy.deepcopy(
+                            new_secnumber
+                        )
                         if ref in env.tocs:
                             self.__replace_toc(env, ref, env.tocs[ref], style)
 
@@ -102,21 +107,26 @@ def assign_section_numbers(self, env):
                         # same length, so probably same numbering depth, so compare one level up
                         if secnumber[:-1] == new_secnumber[:-1]:
                             continue  # skip already updated
-                    # if this point is reached for any anchor, we need to update this anchors secnumber
+                    # if this point is reached for any anchor,
+                    # we need to update this anchors secnumber
                     # to the new secnumber for the overlapping part
                     update_secnumber = list(secnumber)  # make a copy
                     for i in range(renumber_depth):
                         if (
                             secnumber[i] == old_secnumber[i]
                         ):  # only if the old matches the current
                             update_secnumber[i] = new_secnumber[i]
-                    env.toc_secnumbers[doc][anchor] = copy.deepcopy(update_secnumber)
+                    env.toc_secnumbers[doc][anchor] = copy.deepcopy(
+                        update_secnumber
+                    )
 
         # now iterate over env.toc_secnumbers to ensure all secnumbers are updated
         # at the same time
         for docname in env.toc_secnumbers:
             # get the new and old secnumbers for this docname
-            old_secnumber = env.titles_old.get(docname, {}).get("secnumber", None)
+            old_secnumber = env.titles_old.get(docname, {}).get(
+                "secnumber", None
+            )
             new_secnumber = env.titles[docname].get("secnumber", None)
             renumber_depth = len(new_secnumber) if new_secnumber else 0
             # iterate over all anchors in this docname
@@ -137,23 +147,30 @@ def assign_section_numbers(self, env):
                         secnumber[i] == old_secnumber[i]
                     ):  # only if the old matches the current
                         update_secnumber[i] = new_secnumber[i]
-                env.toc_secnumbers[doc][anchor] = copy.deepcopy(update_secnumber)
+                env.toc_secnumbers[doc][anchor] = copy.deepcopy(
+                    update_secnumber
+                )
 
-        # Now, convert all secnumbers in toc_secnumbers to tuples to avoid issues with other steps in the algorithm
+        # Now, convert all secnumbers in toc_secnumbers to tuples
+        # to avoid issues with other steps in the algorithm
         for docname in env.toc_secnumbers:
             for anchorname, secnumber in env.toc_secnumbers[docname].items():
                 if not secnumber:
                     continue
                 secnumber = (*secnumber,)  # convert to tuple
-                env.toc_secnumbers[docname][anchorname] = copy.deepcopy(secnumber)
+                env.toc_secnumbers[docname][anchorname] = copy.deepcopy(
+                    secnumber
+                )
         return result
 
     def __renumber(self, number_set, style_set):
         if not number_set or not style_set:
             return number_set
 
         if not isinstance(style_set, list):
-            style_set = [style_set]  # if not multiple styles are given, convert to list
+            style_set = [
+                style_set
+            ]  # if not multiple styles are given, convert to list
         # for each style, convert the corresponding number, where only the first number
         # is rebased, the rest are kept as is, but converted.
         # convert the first number to the new style
@@ -191,7 +208,21 @@ def __renumber(self, number_set, style_set):
     def __to_roman(self, n):
         """Convert an integer to a Roman numeral."""
         val = [1000, 900, 500, 400, 100, 90, 50, 40, 10, 9, 5, 4, 1]
-        syms = ["M", "CM", "D", "CD", "C", "XC", "L", "XL", "X", "IX", "V", "IV", "I"]
+        syms = [
+            "M",
+            "CM",
+            "D",
+            "CD",
+            "C",
+            "XC",
+            "L",
+            "XL",
+            "X",
+            "IX",
+            "V",
+            "IV",
+            "I",
+        ]
         roman_num = ""
         i = 0
         while n > 0:
@@ -227,7 +258,9 @@ def __fix_nested_toc(self, env, toctree, style):
         for _, ref in toctree["entries"]:
             if "secnumber" not in env.titles[ref]:
                 continue
-            new_secnumber = self.__renumber(env.titles[ref]["secnumber"], style)
+            new_secnumber = self.__renumber(
+                env.titles[ref]["secnumber"], style
+            )
             env.titles[ref]["secnumber"] = copy.deepcopy(new_secnumber)
             if ref in env.tocs:
                 self.__replace_toc(env, ref, env.tocs[ref], style)