🐛 FIX: external_toc_path with absolute path (#25)

Author: chrisjsewell

README.md

@@ -27,7 +27,7 @@ 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.
+Note the `external_toc_path` is always read as a Unix path, and can either be specified relative to the source directory (recommended) or as an absolute path.
 
 ### Basic Structure
 

sphinx_external_toc/events.py

@@ -59,11 +59,16 @@ 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}"
-        )
+    # TODO this seems to work in the tests, but I still want to double check
+    external_toc_path = PurePosixPath(app.config["external_toc_path"])
+    if not external_toc_path.is_absolute():
+        path = Path(app.srcdir) / str(external_toc_path)
+    else:
+        path = Path(str(external_toc_path))
+    if not path.exists():
+        raise ExtensionError(f"[etoc] `external_toc_path` does not exist: {path}")
+    if not path.is_file():
+        raise ExtensionError(f"[etoc] `external_toc_path` is not a file: {path}")
     try:
         site_map = parse_toc_yaml(path)
     except Exception as exc:

tests/test_sphinx.py

@@ -94,3 +94,21 @@ def test_warning(path: Path, tmp_path: Path, sphinx_build_factory):
     builder = sphinx_build_factory(src_dir)
     builder.build(assert_pass=False)
     assert sitemap.meta["expected_warning"] in builder.warnings
+
+
+def test_absolute_path(tmp_path: Path, sphinx_build_factory):
+    """Test if `external_toc_path` is supplied as an absolute path."""
+    src_dir = tmp_path / "srcdir"
+    # write document files
+    toc_path = Path(__file__).parent.joinpath("_toc_files", "basic.yml")
+    create_site_from_toc(toc_path, root_path=src_dir, toc_name=None)
+    # write conf.py
+    content = f"""
+extensions = ["sphinx_external_toc"]
+external_toc_path = {Path(os.path.abspath(toc_path)).as_posix()!r}
+
+"""
+    src_dir.joinpath("conf.py").write_text(content, encoding="utf8")
+    # run sphinx
+    builder = sphinx_build_factory(src_dir)
+    builder.build()