🔧 MAINTAIN: Updated parser docstrings (#61)

Author: ZviBaratz

sphinx_external_toc/parsing.py

@@ -29,26 +29,28 @@
 class FileFormat:
     """Mapping of keys for subtrees and items, dependant on depth in the ToC."""
 
-    subtrees_keys: Sequence[str] = attr.ib(())
-    items_keys: Sequence[str] = attr.ib(())
-    default_subtrees_key: str = attr.ib(DEFAULT_SUBTREES_KEY)
-    default_items_key: str = attr.ib(DEFAULT_ITEMS_KEY)
     toc_defaults: Dict[str, Any] = attr.ib(factory=dict)
+    subtrees_keys: Sequence[str] = attr.ib(default=())
+    items_keys: Sequence[str] = attr.ib(default=())
+    default_subtrees_key: str = attr.ib(default=DEFAULT_SUBTREES_KEY)
+    default_items_key: str = attr.ib(default=DEFAULT_ITEMS_KEY)
 
     def get_subtrees_key(self, depth: int) -> str:
-        """Get the subtrees key name for this depth in the ToC
+        """Get the subtrees key name for this depth in the ToC.
 
         :param depth: recursive depth (starts at 0)
+        :return: subtrees key name
         """
         try:
             return self.subtrees_keys[depth]
         except IndexError:
             return self.default_subtrees_key
 
     def get_items_key(self, depth: int) -> str:
-        """Get the items key name for this depth in the ToC
+        """Get the items key name for this depth in the ToC.
 
         :param depth: recursive depth (starts at 0)
+        :return: items key name
         """
         try:
             return self.items_keys[depth]
@@ -72,18 +74,27 @@ def get_items_key(self, depth: int) -> str:
 
 
 class MalformedError(Exception):
-    """Raised if toc file is malformed."""
+    """Raised if the `_toc.yml` file is malformed."""
 
 
 def parse_toc_yaml(path: Union[str, Path], encoding: str = "utf8") -> SiteMap:
-    """Parse the ToC file."""
+    """Parse the ToC file.
+
+    :param path: `_toc.yml` file path
+    :param encoding: `_toc.yml` file character encoding
+    :return: parsed site map
+    """
     with Path(path).open(encoding=encoding) as handle:
         data = yaml.safe_load(handle)
     return parse_toc_data(data)
 
 
 def parse_toc_data(data: Dict[str, Any]) -> SiteMap:
-    """Parse a dictionary of the ToC."""
+    """Parse a dictionary of the ToC.
+
+    :param data: ToC data dictionary
+    :return: parsed site map
+    """
     if not isinstance(data, Mapping):
         raise MalformedError(f"toc is not a mapping: {type(data)}")
 
@@ -95,14 +106,19 @@ def parse_toc_data(data: Dict[str, Any]) -> SiteMap:
             f"'{data.get(FILE_FORMAT_KEY, 'default')}'"
         )
 
-    defaults: Dict[str, Any] = {**file_format.toc_defaults, **data.get("defaults", {})}
+    defaults: Dict[str, Any] = {
+        **file_format.toc_defaults,
+        **data.get("defaults", {}),
+    }
 
     doc_item, docs_list = _parse_doc_item(
         data, defaults, "/", depth=0, is_root=True, file_format=file_format
     )
 
     site_map = SiteMap(
-        root=doc_item, meta=data.get("meta"), file_format=data.get(FILE_FORMAT_KEY)
+        root=doc_item,
+        meta=data.get("meta"),
+        file_format=data.get(FILE_FORMAT_KEY),
     )
 
     _parse_docs_list(
@@ -121,7 +137,17 @@ def _parse_doc_item(
     file_format: FileFormat,
     is_root: bool = False,
 ) -> Tuple[Document, Sequence[Tuple[str, Dict[str, Any]]]]:
-    """Parse a single doc item."""
+    """Parse a single doc item.
+
+    :param data: doc item dictionary
+    :param defaults: doc item defaults dictionary
+    :param path: doc item file path
+    :param depth: recursive depth (starts at 0)
+    :param file_format: doc item file format
+    :param is_root: whether this is the root item, defaults to False
+    :raises MalformedError: invalid doc item
+    :return: parsed doc item
+    """
     file_key = ROOT_KEY if is_root else FILE_KEY
     if file_key not in data:
         raise MalformedError(f"'{file_key}' key not found @ '{path}'")
@@ -275,13 +301,26 @@ def _parse_docs_list(
     depth: int,
     file_format: FileFormat,
 ):
-    """Parse a list of docs."""
+    """Parse a list of docs.
+
+    :param docs_list: sequence of doc items
+    :param site_map: site map
+    :param defaults: default doc item values
+    :param path: file path, unused
+    :param depth: recursive depth (starts at 0)
+    :param file_format: doc item file format
+    :raises MalformedError: doc file used multiple times
+    """
     for child_path, doc_data in docs_list:
         docname = doc_data[FILE_KEY]
         if docname in site_map:
             raise MalformedError(f"document file used multiple times: '{docname}'")
         child_item, child_docs_list = _parse_doc_item(
-            doc_data, defaults, child_path, depth=depth, file_format=file_format
+            doc_data,
+            defaults,
+            child_path,
+            depth=depth,
+            file_format=file_format,
         )
         site_map[docname] = child_item
 
@@ -296,7 +335,13 @@ def _parse_docs_list(
 
 
 def create_toc_dict(site_map: SiteMap, *, skip_defaults: bool = True) -> Dict[str, Any]:
-    """Create the Toc dictionary from a site-map."""
+    """Create the ToC dictionary from a site-map.
+
+    :param site_map: site map
+    :param skip_defaults: do not add key/values for values that are already the default
+    :raises KeyError: invalid file format
+    :return: ToC dictionary
+    """
     try:
         file_format = FILE_FORMATS[site_map.file_format or "default"]
     except KeyError:
@@ -327,10 +372,19 @@ def _docitem_to_dict(
     is_root: bool = False,
     parsed_docnames: Optional[Set[str]] = None,
 ) -> Dict[str, Any]:
-    """
+    """Create ToC dictionary from a `Document` and a `SiteMap`.
 
+    :param doc_item: document instance
+    :param site_map: site map
+    :param depth: recursive depth (starts at 0)
+    :param file_format: doc item file format
     :param skip_defaults: do not add key/values for values that are already the default
-
+    :param is_root: whether this is the root item, defaults to False
+    :param parsed_docnames: parsed document names cache used to prevent infinite
+        recursion
+    :raises RecursionError: site map recursion
+    :raises TypeError: invalid ToC item
+    :return: parsed ToC dictionary
     """
     file_key = ROOT_KEY if is_root else FILE_KEY
     subtrees_key = file_format.get_subtrees_key(depth)