♻️ REFACTOR: API naming

Renamed to be more general:

- `DocItem` -> `Document`
- `DocItem.parts` -> `Document.subtrees`
- `TocItem` -> `TocTree`
- `TocItem.sections` -> `TocTree.items`

Author: chrisjsewell

README.md

@@ -321,7 +321,7 @@ sections:
 
 ## API
 
-The ToC file is parsed to a `SiteMap`, which is a `MutableMapping` subclass, with keys representing docnames mapping to a `DocItem` that stores information on the toctrees it should contain:
+The ToC file is parsed to a `SiteMap`, which is a `MutableMapping` subclass, with keys representing docnames mapping to a `Document` that stores information on the toctrees it should contain:
 
 ```python
 import yaml
@@ -334,21 +334,23 @@ yaml.dump(site_map.as_json())
 Would produce e.g.
 
 ```yaml
-_root: intro
-doc1:
-  docname: doc1
-  parts: []
-  title: null
-intro:
-  docname: intro
-  parts:
-  - caption: Part Caption
-    numbered: true
-    reversed: false
-    sections:
-    - doc1
-    titlesonly: true
-  title: null
+root: intro
+documents:
+  doc1:
+    docname: doc1
+    subtrees: []
+    title: null
+  intro:
+    docname: intro
+    subtrees:
+    - caption: Part Caption
+      numbered: true
+      reversed: false
+      items:
+      - doc1
+      titlesonly: true
+    title: null
+meta: {}
 ```
 
 ## Development Notes

sphinx_external_toc/api.py

@@ -28,11 +28,11 @@ class UrlItem:
 
 
 @attr.s(slots=True)
-class TocItem:
+class TocTree:
     """An individual toctree within a document."""
 
     # TODO validate uniqueness of docnames (at least one item)
-    sections: List[Union[GlobItem, FileItem, UrlItem]] = attr.ib(
+    items: List[Union[GlobItem, FileItem, UrlItem]] = attr.ib(
         validator=deep_iterable(
             instance_of((GlobItem, FileItem, UrlItem)), instance_of(list)
         )
@@ -49,47 +49,43 @@ class TocItem:
     titlesonly: bool = attr.ib(True, kw_only=True, validator=instance_of(bool))
 
     def files(self) -> List[str]:
-        return [
-            str(section) for section in self.sections if isinstance(section, FileItem)
-        ]
+        return [str(item) for item in self.items if isinstance(item, FileItem)]
 
     def globs(self) -> List[str]:
-        return [
-            str(section) for section in self.sections if isinstance(section, GlobItem)
-        ]
+        return [str(item) for item in self.items if isinstance(item, GlobItem)]
 
 
 @attr.s(slots=True)
-class DocItem:
+class Document:
     """A document in the site map."""
 
     docname: str = attr.ib(validator=instance_of(str))
     title: Optional[str] = attr.ib(None, validator=optional(instance_of(str)))
     # TODO validate uniqueness of docnames across all parts (and none should be the docname)
-    parts: List[TocItem] = attr.ib(
-        factory=list, validator=deep_iterable(instance_of(TocItem), instance_of(list))
+    subtrees: List[TocTree] = attr.ib(
+        factory=list, validator=deep_iterable(instance_of(TocTree), instance_of(list))
     )
 
     def child_files(self) -> List[str]:
         """Return all children files."""
-        return [name for part in self.parts for name in part.files()]
+        return [name for tree in self.subtrees for name in tree.files()]
 
     def child_globs(self) -> List[str]:
         """Return all children globs."""
-        return [name for part in self.parts for name in part.globs()]
+        return [name for tree in self.subtrees for name in tree.globs()]
 
 
 class SiteMap(MutableMapping):
     """A mapping of documents to their toctrees (or None if terminal)."""
 
-    def __init__(self, root: DocItem, meta: Optional[Dict[str, Any]] = None) -> None:
-        self._docs: Dict[str, DocItem] = {}
+    def __init__(self, root: Document, meta: Optional[Dict[str, Any]] = None) -> None:
+        self._docs: Dict[str, Document] = {}
         self[root.docname] = root
-        self._root: DocItem = root
+        self._root: Document = root
         self._meta: Dict[str, Any] = meta or {}
 
     @property
-    def root(self) -> DocItem:
+    def root(self) -> Document:
         """Return the root document."""
         return self._root
 
@@ -102,10 +98,10 @@ 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()}
 
-    def __getitem__(self, docname: str) -> DocItem:
+    def __getitem__(self, docname: str) -> Document:
         return self._docs[docname]
 
-    def __setitem__(self, docname: str, item: DocItem) -> None:
+    def __setitem__(self, docname: str, item: Document) -> None:
         assert item.docname == docname
         self._docs[docname] = item
 
@@ -130,17 +126,12 @@ def _serializer(inst: Any, field: attr.Attribute, value: Any) -> Any:
             return str(value)
         return value
 
-    def as_json(
-        self, root_key: str = "_root", meta_key: str = "_meta"
-    ) -> Dict[str, Any]:
+    def as_json(self) -> Dict[str, Any]:
         """Return JSON serialized site-map representation."""
-        dct = {
-            k: attr.asdict(v, value_serializer=self._serializer) if v else v
-            for k, v in self._docs.items()
+        doc_dict = {
+            k: attr.asdict(self._docs[k], value_serializer=self._serializer)
+            if self._docs[k]
+            else self._docs[k]
+            for k in sorted(self._docs)
         }
-        assert root_key not in dct
-        dct[root_key] = self.root.docname
-        if self.meta:
-            assert meta_key not in dct
-            dct[meta_key] = self.meta
-        return dct
+        return {"root": self.root.docname, "documents": doc_dict, "meta": self.meta}

sphinx_external_toc/cli.py

@@ -23,7 +23,7 @@ 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()))
+    click.echo(yaml.dump(site_map.as_json(), sort_keys=False, default_flow_style=False))
 
 
 @main.command("create-site")

sphinx_external_toc/events.py

@@ -14,7 +14,7 @@
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.matching import Matcher, patfilter, patmatch
 
-from .api import DocItem, FileItem, GlobItem, SiteMap, UrlItem
+from .api import Document, FileItem, GlobItem, SiteMap, UrlItem
 from .parsing import parse_toc_yaml
 
 logger = logging.getLogger(__name__)
@@ -166,9 +166,9 @@ def insert_toctrees(app: Sphinx, doctree: nodes.document) -> None:
     )
 
     site_map: SiteMap = app.env.external_site_map
-    doc_item: Optional[DocItem] = site_map.get(app.env.docname)
+    doc_item: Optional[Document] = site_map.get(app.env.docname)
 
-    if doc_item is None or not doc_item.parts:
+    if doc_item is None or not doc_item.subtrees:
         if toc_placeholders:
             create_warning(
                 app,
@@ -199,7 +199,7 @@ def insert_toctrees(app: Sphinx, doctree: nodes.document) -> None:
 
     node_list: List[nodes.Element] = []
 
-    for toctree in doc_item.parts:
+    for toctree in doc_item.subtrees:
 
         subnode = toctree_node()
         subnode["parent"] = app.env.docname
@@ -211,7 +211,7 @@ def insert_toctrees(app: Sphinx, doctree: nodes.document) -> None:
         # TODO this wasn't in the original code,
         # but alabaster theme intermittently raised `KeyError('rawcaption')`
         subnode["rawcaption"] = toctree.caption or ""
-        subnode["glob"] = any(isinstance(entry, GlobItem) for entry in toctree.sections)
+        subnode["glob"] = any(isinstance(entry, GlobItem) for entry in toctree.items)
         subnode["hidden"] = False if toc_placeholders else toctree.hidden
         subnode["includehidden"] = False
         subnode["numbered"] = (
@@ -223,7 +223,7 @@ def insert_toctrees(app: Sphinx, doctree: nodes.document) -> None:
         wrappernode = nodes.compound(classes=["toctree-wrapper"])
         wrappernode.append(subnode)
 
-        for entry in toctree.sections:
+        for entry in toctree.items:
 
             if isinstance(entry, UrlItem):
 

sphinx_external_toc/parsing.py

@@ -6,7 +6,7 @@
 import attr
 import yaml
 
-from .api import DocItem, FileItem, GlobItem, SiteMap, TocItem, UrlItem
+from .api import Document, FileItem, GlobItem, SiteMap, TocTree, UrlItem
 
 FILE_KEY = "file"
 GLOB_KEY = "glob"
@@ -51,7 +51,7 @@ def parse_toc_data(data: Dict[str, Any]) -> SiteMap:
 
 def _parse_doc_item(
     data: Dict[str, Any], defaults: Dict[str, Any], path: str, file_key: str = FILE_KEY
-) -> Tuple[DocItem, Sequence[Dict[str, Any]]]:
+) -> Tuple[Document, Sequence[Dict[str, Any]]]:
     """Parse a single doc item."""
     if file_key not in data:
         raise MalformedError(f"'{file_key}' key not found: '{path}'")
@@ -127,13 +127,15 @@ def _parse_doc_item(
                 keywords[key] = defaults[key]
 
         try:
-            toc_item = TocItem(sections=sections, **keywords)
+            toc_item = TocTree(items=sections, **keywords)
         except TypeError as exc:
             raise MalformedError(f"toctree validation: {path}{part_idx}") from exc
         parts.append(toc_item)
 
     try:
-        doc_item = DocItem(docname=data[file_key], title=data.get("title"), parts=parts)
+        doc_item = Document(
+            docname=data[file_key], title=data.get("title"), subtrees=parts
+        )
     except TypeError as exc:
         raise MalformedError(f"doc validation: {path}") from exc
 
@@ -179,7 +181,7 @@ def create_toc_dict(site_map: SiteMap, *, skip_defaults: bool = True) -> Dict[st
 
 
 def _docitem_to_dict(
-    doc_item: DocItem,
+    doc_item: Document,
     site_map: SiteMap,
     *,
     skip_defaults: bool = True,
@@ -199,7 +201,7 @@ def _docitem_to_dict(
     if doc_item.title is not None:
         data["title"] = doc_item.title
 
-    if not doc_item.parts:
+    if not doc_item.subtrees:
         return data
 
     def _parse_section(item):
@@ -221,15 +223,15 @@ def _parse_section(item):
         raise TypeError(item)
 
     data["parts"] = []
-    fields = attr.fields_dict(TocItem)
-    for part in doc_item.parts:
+    fields = attr.fields_dict(TocTree)
+    for part in doc_item.subtrees:
         # only add these keys if their value is not the default
         part_data = {
             key: getattr(part, key)
             for key in ("caption", "numbered", "reversed", "titlesonly")
             if (not skip_defaults) or getattr(part, key) != fields[key].default
         }
-        part_data["sections"] = [_parse_section(s) for s in part.sections]
+        part_data["sections"] = [_parse_section(s) for s in part.items]
         data["parts"].append(part_data)
 
     # apply shorthand if possible

sphinx_external_toc/tools.py

@@ -7,7 +7,7 @@
 
 import yaml
 
-from .api import DocItem, FileItem, SiteMap, TocItem
+from .api import Document, FileItem, SiteMap, TocTree
 from .parsing import MalformedError, parse_toc_yaml
 
 
@@ -129,15 +129,15 @@ def create_site_map_from_path(
     # we add all files to the site map, even if they don't have descendants
     # so we may later change their title
     for root_file in root_files:
-        site_map[root_file] = DocItem(root_file)
+        site_map[root_file] = Document(root_file)
 
     # while there are subfolders add them to the site-map
     while indexed_folders:
         sub_path, child_index, child_files, child_folders = indexed_folders.pop(0)
         for child_file in child_files:
             child_docname = (sub_path / child_file).relative_to(root_path).as_posix()
             assert child_docname not in site_map
-            site_map[child_docname] = DocItem(child_docname)
+            site_map[child_docname] = Document(child_docname)
         doc_item, new_indexed_folders = _doc_item_from_path(
             root_path,
             sub_path,
@@ -164,7 +164,7 @@ def _doc_item_from_path(
     default_index: str,
     ignore_matches: Sequence[str],
 ):
-    """Return the ``DocItem`` and children folders that contain an index."""
+    """Return the ``Document`` and children folders that contain an index."""
     file_items = [
         FileItem((folder / name).relative_to(root).as_posix())
         for name in other_docnames
@@ -186,9 +186,9 @@ def _doc_item_from_path(
             FileItem((sub_folder / child_index).relative_to(root).as_posix())
         )
 
-    doc_item = DocItem(
+    doc_item = Document(
         docname=(folder / index_docname).relative_to(root).as_posix(),
-        parts=[TocItem(sections=file_items + index_items)]  # type: ignore[arg-type]
+        subtrees=[TocTree(items=file_items + index_items)]  # type: ignore[arg-type]
         if (file_items or index_items)
         else [],
     )