👌 IMPROVE: toc.yml validation

Author: chrisjsewell

README.md

@@ -23,6 +23,8 @@ external_toc_path = "_toc.yml"  # optional, default: _toc.yml
 external_toc_exclude_missing = False  # optional, default: False
 ```
 
+Note the `external_toc_path` is always read as a Unix path.
+
 ### Basic Structure
 
 A minimal ToC defines the top level `root` key, for a single root document file:
@@ -326,6 +328,9 @@ Questions / TODOs:
 - test against orphan file
 - https://github.com/executablebooks/sphinx-book-theme/pull/304
 - CLI command to generate toc from existing documentation `toctrees` (and then remove toctree directives)
+- test rebuild on toc changes (and document how rebuilds are controlled when toc changes)
+- some jupyter-book issues point to potential changes in numbering, based on where the `toctree` is in the document.
+  So could look into placing it e.g. under the first heading/title
 
 [github-ci]: https://github.com/executablebooks/sphinx-external-toc/workflows/continuous-integration/badge.svg?branch=main
 [github-link]: https://github.com/executablebooks/sphinx-external-toc

sphinx_external_toc/api.py

@@ -161,7 +161,7 @@ def parse_toc_yaml(path: Union[str, Path], encoding: str = "utf8") -> SiteMap:
 def parse_toc_data(data: Dict[str, Any]) -> SiteMap:
     """Parse a dictionary of the ToC."""
     if not isinstance(data, Mapping):
-        MalformedError(f"toc is not a mapping: {type(data)}")
+        raise MalformedError(f"toc is not a mapping: {type(data)}")
 
     defaults: Dict[str, Any] = data.get("defaults", {})
 
@@ -210,11 +210,22 @@ def _parse_doc_item(
                     "toctree section contains incompatible keys "
                     f"{link_keys!r}: {path}{part_idx}/{sect_idx}"
                 )
+
             if link_keys == {FILE_KEY}:
                 sections.append(FileItem(section[FILE_KEY]))
             elif link_keys == {GLOB_KEY}:
+                if "sections" in section or "parts" in section:
+                    raise MalformedError(
+                        "toctree section contains incompatible keys "
+                        f"{GLOB_KEY} and parts/sections: {path}{part_idx}/{sect_idx}"
+                    )
                 sections.append(GlobItem(section[GLOB_KEY]))
             elif link_keys == {URL_KEY}:
+                if "sections" in section or "parts" in section:
+                    raise MalformedError(
+                        "toctree section contains incompatible keys "
+                        f"{URL_KEY} and parts/sections: {path}{part_idx}/{sect_idx}"
+                    )
                 sections.append(UrlItem(section[URL_KEY], section.get("title")))
 
         # generate toc key-word arguments

sphinx_external_toc/events.py

@@ -1,6 +1,6 @@
 """Sphinx event functions and directives."""
 import glob
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from typing import Any, List, Optional, Set
 
 from docutils import nodes
@@ -50,8 +50,13 @@ def parse_toc_to_env(app: Sphinx, config: Config) -> None:
 
     Also, change the ``master_doc`` and add to ``exclude_patterns`` if necessary.
     """
+    path = Path(app.srcdir) / PurePosixPath(app.config["external_toc_path"])
+    if not (path.exists() and path.is_file()):
+        raise ExtensionError(
+            f"[etoc] `external_toc_path` is not an existing file: {path}"
+        )
     try:
-        site_map = parse_toc_yaml(Path(app.srcdir) / app.config["external_toc_path"])
+        site_map = parse_toc_yaml(path)
     except Exception as exc:
         raise ExtensionError(f"[etoc] {exc}") from exc
     config.external_site_map = site_map