fix: Specifications from parents of Sphinx source directory (#264)

* fix: Specifications from parents of source dir

If a spec is referenced with `../../../and-so-on/`
to access a file from a parent of the Sphinx
source directory, the resolved path can be
a path that is a parent of the output HTML directory.

By replacing the ".." with "dot-dot" in the output
of the Sphinx relfn2path function, this fix
ensures that the spec is copied correctly to
a subdirectory of the output `_static` directory.

For example, expect to see `_static/dot-dot/dot-dot/openapi.yaml`.
That path would otherwise be a parent of the output HTML.

Signed-off-by: Mike McKiernan <[email protected]>

* chore: Update version for patch release

Signed-off-by: Mike McKiernan <[email protected]>

---------

Signed-off-by: Mike McKiernan <[email protected]>

Author: mikemckiernan

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 5.1.1
+
+* Fixed a bug related to referencing a specification from a parent
+  directory of the Sphinx source directory, such as when documentation
+  is co-located with source code.
+
+  Before this fix, when a specification was several subdirectories
+  from the documentation, the specification could be copied to
+  a parent directory of the build HTML output and prevent the display
+  of the specification.
+
+  With this fix, deeply nested specifications (`../../../../openapi.yaml`)
+  have the `..` values that are parents of the Sphinx source directory
+  replaced with the text `dot-dot`. This fix ensures that deeply
+  nested specifications are copied to a subdirectory of the `_static`
+  directory in the HTML output.
+
 ## 5.1.0
 
 * Refactored copying the specification to the HTML output and

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swagger-plugin-for-sphinx"
-version = "5.1.0"
+version = "5.1.1"
 description = "Sphinx plugin which renders a OpenAPI specification with Swagger"
 authors = [{ name = "Kai Harder", email = "[email protected]" }]
 readme = "README.md"

swagger_plugin_for_sphinx/_plugin.py

@@ -59,6 +59,9 @@ def run(self) -> list[nodes.Node]:
             )
 
         relpath, abspath = self.env.relfn2path(self.arguments[0])
+        # Use dot-dot to address referencing specs from parents of the Sphinx source directory.
+        # Otherwise, the spec is copied to a parent of the output directory.
+        relpath = relpath.replace("..", "dot-dot")
         spec = Path(abspath).resolve()
         if not spec.exists():
             raise ExtensionError(

tests/test_plugin.py

@@ -247,6 +247,8 @@ def test_custom_urls(
 @pytest.mark.parametrize("builder", ["html", "dirhtml"])
 def test_subdirs(tmp_path: Path, builder: str) -> None:
     docs = tmp_path / "docs"
+    codedir = tmp_path / "code"  # Imitate copying spec from source.
+    codedir.mkdir(parents=True)
     subdir = docs / "subdir"
     subsubdir = subdir / "subdirtwo"
     subsubdir.mkdir(parents=True)
@@ -258,6 +260,7 @@ def test_subdirs(tmp_path: Path, builder: str) -> None:
     build.mkdir()
 
     spec = Path(__file__).parent / "openapi.yml"
+    shutil.copyfile(str(spec), str(codedir / "openapi.yaml"))
     shutil.copyfile(str(spec), str(speconedir / "openapi.yaml"))
     shutil.copyfile(str(spec), str(spectwodir / "openapi.yaml"))
 
@@ -278,7 +281,18 @@ def test_subdirs(tmp_path: Path, builder: str) -> None:
     )
     two = subsubdir / "two.rst"
     two.write_text(
-        "API Two\n=======\n\n.. swagger-plugin:: ../../api/two/yaml/openapi.yaml\n",
+        dedent(
+            """
+            API Two
+            =======
+
+            .. swagger-plugin:: ../../api/two/yaml/openapi.yaml
+               :id: from-docs
+
+            .. swagger-plugin:: ../../../code/openapi.yaml
+               :id: from-code
+            """
+        ),
         encoding="utf-8",
     )
 
@@ -303,8 +317,10 @@ def test_subdirs(tmp_path: Path, builder: str) -> None:
             build / "subdir" / "subdirtwo" / "two.html", encoding="utf-8"
         ) as file:
             html = file.read()
-            assert "#swagger-ui-container" in html
+            assert "#from-docs" in html
+            assert "#from-code" in html
             assert "../../_static/api/two/yaml/openapi.yaml" in html
+            assert "../../_static/dot-dot/code/openapi.yaml" in html
 
     if builder == "dirhtml":
         with open(build / "subdir" / "one" / "index.html", encoding="utf-8") as file:
@@ -316,3 +332,4 @@ def test_subdirs(tmp_path: Path, builder: str) -> None:
         ) as file:
             html = file.read()
             assert "../../../_static/api/two/yaml/openapi.yaml" in html
+            assert "../../../_static/dot-dot/code/openapi.yaml" in html