sphinx-codeautolink 0.17.2__tar.gz → 0.17.4__tar.gz

{sphinx_codeautolink-0.17.2/src/sphinx_codeautolink.egg-info → sphinx_codeautolink-0.17.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: sphinx-codeautolink
-Version: 0.17.2
+Version: 0.17.4
 Summary: Automatic links from code examples to reference documentation.
 Author-email: Felix Hildén <felix.hilden@gmail.com>
 Maintainer-email: Felix Hildén <felix.hilden@gmail.com>

{sphinx_codeautolink-0.17.2 → sphinx_codeautolink-0.17.4}/contributing.rst

@@ -37,6 +37,16 @@ For tips and tricks on contributing, see `how to submit a contribution
 specifically `opening a pull request
 <https://opensource.guide/how-to-contribute/#opening-a-pull-request>`_.
 
+If you want to contribute to someone else's fork and find yourself forgetting
+how to do it every time, here's the runbook:
+
+.. code:: sh
+
+   git remote add [name] git@github.com:[name]/sphinx-codeautolink.git
+   git fetch [name]
+   git switch -c branch [name]/branch
+   git remote rm [name]
+
 Testing
 -------
 The installation can be verified, and any changes tested by running tox.

{sphinx_codeautolink-0.17.2 → sphinx_codeautolink-0.17.4}/docs/src/about.rst

@@ -16,8 +16,8 @@ is injected after the ordinary Sphinx build is finished.
 
 Caveats
 -------
-- **Only works with HTML documentation**, disabled otherwise. If the extension
-  is off, it silently removes directives that would produce output.
+- **Only works with HTML or DIRHTML documentation**, disabled otherwise. If the
+  extension is off, it silently removes directives that would produce output.
 - **Only processes blocks, not inline code**. Sphinx has great tools
   for linking definitions inline, and longer code should be in a block anyway.
 - **Doesn't run example code**. Therefore all possible resolvable types are not

{sphinx_codeautolink-0.17.2 → sphinx_codeautolink-0.17.4}/docs/src/index.rst

@@ -68,7 +68,7 @@ Caveats
 -------
 For a more thorough explanation, see :ref:`about`.
 
-- Only works with HTML documentation
+- Only works with HTML or DIRHTML documentation
 - Only processes blocks, not inline code
 - Doesn't run example code
 - Parsing and type hint resolving is incomplete

{sphinx_codeautolink-0.17.2 → sphinx_codeautolink-0.17.4}/docs/src/release_notes.rst

@@ -8,6 +8,15 @@ These release notes are based on
 sphinx-codeautolink adheres to
 `Semantic Versioning <https://semver.org>`_.
 
+0.17.4 (2025-03-07)
+-------------------
+- Fix backreference links using relative URIs (:issue:`190`)
+
+0.17.3 (2025-03-06)
+-------------------
+- Fix Sphinx InventoryItem deprecation warning (:issue:`173`)
+- Add support for the DIRHTML Sphinx builder (:issue:`188`)
+
 0.17.2 (2025-03-02)
 -------------------
 - Support :rst:dir:`testsetup` from ``sphinx.ext.doctest`` as another

{sphinx_codeautolink-0.17.2 → sphinx_codeautolink-0.17.4}/pyproject.toml

@@ -48,6 +48,9 @@ version = {attr = "sphinx_codeautolink.__version__"}
 [tool.pytest.ini_options]
 python_files = "*.py"
 testpaths = ["tests"]
+filterwarnings = [
+    "ignore:.*IPython:UserWarning",
+]
 
 [tool.coverage.run]
 source = ["src"]

{sphinx_codeautolink-0.17.2 → sphinx_codeautolink-0.17.4}/src/sphinx_codeautolink/__init__.py

@@ -8,7 +8,7 @@ from .extension import SphinxCodeAutoLink, backref, directive
 from .extension.block import clean_ipython, clean_pycon
 from .extension.translation import MESSAGE_CATALOG_NAME
 
-__version__ = "0.17.2"
+__version__ = "0.17.4"
 
 
 def setup(app: Sphinx):

{sphinx_codeautolink-0.17.2 → sphinx_codeautolink-0.17.4}/src/sphinx_codeautolink/extension/__init__.py

@@ -7,6 +7,7 @@ from functools import wraps
 from pathlib import Path
 from traceback import print_exc
 
+from sphinx import version_info as sphinx_version
 from sphinx.ext.intersphinx import InventoryAdapter
 from sphinx.util import import_object
 
@@ -89,7 +90,7 @@ class SphinxCodeAutoLink:
     @print_exceptions()
     def build_inited(self, app) -> None:
         """Handle initial setup."""
-        if app.builder.name != "html":
+        if app.builder.name not in ("html", "dirhtml"):
             self.do_nothing = True
             return
 
@@ -177,7 +178,9 @@ class SphinxCodeAutoLink:
         }
         inter_inv = InventoryAdapter(app.env).main_inventory
         transposed = transpose_inventory(inter_inv, relative_to=app.outdir)
-        transposed.update(transpose_inventory(inventory, relative_to=app.outdir))
+        transposed.update(
+            transpose_inventory(inventory, relative_to=app.outdir, use_tuple=True)
+        )
         return transposed
 
     @print_exceptions()
@@ -268,6 +271,8 @@ class SphinxCodeAutoLink:
         visitor = CodeRefsVisitor(
             doctree,
             code_refs=self.code_refs,
+            docname=docname,
+            builder=app.builder,
             warn_no_backreference=self.warn_no_backreference,
         )
         doctree.walk(visitor)
@@ -289,12 +294,15 @@ class SphinxCodeAutoLink:
                 self.inventory,
                 self.custom_blocks,
                 self.search_css_classes,
+                builder_name=app.builder.name,
             )
 
         self.cache.write()
 
 
-def transpose_inventory(inv: dict, relative_to: str) -> dict[str, str]:
+def transpose_inventory(
+    inv: dict, relative_to: str, *, use_tuple: bool = False
+) -> dict[str, str]:
     """
     Transpose Sphinx inventory from {type: {name: (..., location)}} to {name: location}.
 
@@ -306,13 +314,18 @@ def transpose_inventory(inv: dict, relative_to: str) -> dict[str, str]:
         Sphinx inventory
     relative_to
         if a local file is found, transform it to be relative to this dir
+    use_tuple
+        force using Sphinx inventory tuple interface,
+        TODO: move to class interface if it becomes public (#173)
     """
     transposed = {}
     for type_, items in inv.items():
         if not type_.startswith("py:"):
             continue
         for item, info in items.items():
-            location = info[2]
+            location = (
+                info.uri if not use_tuple and sphinx_version >= (8, 2) else info[2]
+            )
             if not location.startswith("http"):
                 location = str(Path(location).relative_to(relative_to))
             transposed[item] = location

{sphinx_codeautolink-0.17.2 → sphinx_codeautolink-0.17.4}/src/sphinx_codeautolink/extension/backref.py

@@ -3,6 +3,7 @@
 from dataclasses import dataclass
 
 from docutils import nodes
+from sphinx.builders import Builder
 
 from sphinx_codeautolink.warn import logger, warn_type
 
@@ -62,11 +63,15 @@ class CodeRefsVisitor(nodes.SparseNodeVisitor):
         self,
         *args,
         code_refs: dict[str, list[CodeExample]],
+        docname: str,
+        builder: Builder,
         warn_no_backreference: bool = False,
         **kwargs,
     ) -> None:
         super().__init__(*args, **kwargs)
         self.code_refs = code_refs
+        self.docname = docname
+        self.builder = builder
         self.warn_no_backreference = warn_no_backreference
 
     def unknown_departure(self, node) -> None:
@@ -79,7 +84,7 @@ class CodeRefsVisitor(nodes.SparseNodeVisitor):
 
         items = []
         for ref in self.code_refs.get(node.ref, []):
-            link = ref.document + ".html"
+            link = self.builder.get_relative_uri(self.docname, ref.document)
             if ref.ref_id is not None:
                 link += f"#{ref.ref_id}"
             items.append((link, " / ".join(ref.headings)))

{sphinx_codeautolink-0.17.2 → sphinx_codeautolink-0.17.4}/src/sphinx_codeautolink/extension/block.py

@@ -375,9 +375,14 @@ def link_html(
     inventory: dict,
     custom_blocks: dict,
     search_css_classes: list,
+    builder_name: str = "html",
 ) -> None:
     """Inject links to code blocks on disk."""
-    html_file = Path(out_dir) / (document + ".html")
+    if builder_name == "dirhtml" and Path(document).name != "index":
+        html_file = Path(out_dir) / document / "index.html"
+    else:
+        html_file = Path(out_dir) / (document + ".html")
+
     text = html_file.read_text("utf-8")
     soup = BeautifulSoup(text, "html.parser")
 

{sphinx_codeautolink-0.17.2 → sphinx_codeautolink-0.17.4/src/sphinx_codeautolink.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: sphinx-codeautolink
-Version: 0.17.2
+Version: 0.17.4
 Summary: Automatic links from code examples to reference documentation.
 Author-email: Felix Hildén <felix.hilden@gmail.com>
 Maintainer-email: Felix Hildén <felix.hilden@gmail.com>

{sphinx_codeautolink-0.17.2 → sphinx_codeautolink-0.17.4}/tests/extension/__init__.py

@@ -9,7 +9,7 @@ import pytest
 from bs4 import BeautifulSoup
 from sphinx.cmd.build import main as sphinx_main
 
-from ._check import check_link_targets
+from ._check import check_link_targets, check_reference_targets_exist
 
 # Insert test package root to path for all tests
 sys.path.insert(0, str(Path(__file__).parent / "src"))
@@ -278,6 +278,7 @@ Test project
 
     for file in subfiles:
         assert_links(result_dir / (file + ".html"), links)
+
     assert check_link_targets(result_dir) == n_subfiles * len(links)
 
 
@@ -312,6 +313,112 @@ Test project
     assert "sphinx-codeautolink-a" in str(blocks[1])
 
 
+def test_dirhtml_builder(tmp_path: Path):
+    index = """
+Test project
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   page1/index
+   page2
+   subdir/page3
+
+Index Page Code
+---------------
+
+.. code:: python
+
+   import test_project
+   test_project.bar()
+
+.. automodule:: test_project
+"""
+
+    page = """
+Page {idx}
+===========
+
+.. code:: python
+
+   import test_project
+   test_project.bar()
+
+.. autolink-examples:: test_project.bar
+"""
+
+    files = {
+        "conf.py": default_conf,
+        "index.rst": index,
+        "page1/index.rst": page.format(idx=1),
+        "page2.rst": page.format(idx=2),
+        "subdir/page3.rst": page.format(idx=3),
+    }
+    links = ["test_project", "test_project.bar"]
+
+    result_dir = _sphinx_build(tmp_path, "dirhtml", files)
+
+    assert_links(result_dir / "index.html", links)
+    assert_links(result_dir / "page1/index.html", links)
+    assert_links(result_dir / "page2/index.html", links)
+    assert_links(result_dir / "subdir/page3/index.html", links)
+
+    assert check_link_targets(result_dir) == len(links) * 4
+    check_reference_targets_exist(result_dir)
+
+
+def test_html_subdir_reference(tmp_path: Path):
+    index = """
+Test project
+============
+
+.. toctree::
+
+   subdir/page1
+   subdir/subdir2/page2
+
+Index Page
+----------
+
+.. code:: python
+
+   import test_project
+   test_project.bar()
+
+.. automodule:: test_project
+"""
+
+    page = """
+Page {idx}
+===========
+
+.. code:: python
+
+   import test_project
+   test_project.bar()
+
+.. autolink-examples:: test_project.bar
+"""
+
+    files = {
+        "conf.py": default_conf,
+        "index.rst": index,
+        "subdir/page1.rst": page.format(idx=1),
+        "subdir/subdir2/page2.rst": page.format(idx=2),
+    }
+    links = ["test_project", "test_project.bar"]
+
+    result_dir = _sphinx_build(tmp_path, "html", files)
+
+    assert_links(result_dir / "index.html", links)
+    assert_links(result_dir / "subdir/page1.html", links)
+    assert_links(result_dir / "subdir/subdir2/page2.html", links)
+
+    assert check_link_targets(result_dir) == len(links) * 3
+    check_reference_targets_exist(result_dir)
+
+
 def _sphinx_build(
     folder: Path, builder: str, files: dict[str, str], n_processes: int | None = None
 ) -> Path:
@@ -319,7 +426,9 @@ def _sphinx_build(
     src_dir = folder / "src"
     src_dir.mkdir(exist_ok=True)
     for name, content in files.items():
-        (src_dir / name).write_text(content, "utf-8")
+        path = src_dir / name
+        path.parent.mkdir(exist_ok=True, parents=True)
+        path.write_text(content, "utf-8")
 
     build_dir = folder / "build"
     args = ["-M", builder, str(src_dir), str(build_dir), "-W"]

sphinx_codeautolink-0.17.4/tests/extension/_check.py

@@ -0,0 +1,68 @@
+from pathlib import Path
+
+import requests
+from bs4 import BeautifulSoup
+
+# Cache external pages for the duration of the runtime,
+# so that we don't request them multiple times needlessly
+sess = requests.Session()
+external_site_ids = {}
+
+
+def check_link_targets(root: Path) -> int:
+    """Validate links in HTML site at root, return number of links found."""
+    site_docs = {
+        p: BeautifulSoup(p.read_text("utf-8"), "html.parser")
+        for p in root.glob("**/*.html")
+    }
+    site_ids = {k: gather_ids(v) for k, v in site_docs.items()}
+
+    total = 0
+    for doc, soup in site_docs.items():
+        for link in soup.find_all("a", attrs={"class": "sphinx-codeautolink-a"}):
+            base, id_ = link["href"].split("#")
+            if any(base.startswith(s) for s in ("http://", "https://")):
+                if base not in external_site_ids:
+                    sub_soup = BeautifulSoup(sess.get(base).text, "html.parser")
+                    external_site_ids[base] = gather_ids(sub_soup)
+                ids = external_site_ids[base]
+            else:
+                target_path = (doc.parent / base).resolve()
+                if target_path.is_dir():
+                    target_path /= "index.html"
+                assert target_path.exists(), (
+                    f"Target path {target_path!s} not found while validating"
+                    f" link for `{link.string}` in {doc.relative_to(root)!s}!"
+                )
+                ids = site_ids[target_path]
+
+            assert id_ in ids, (
+                f"ID {id_} not found in {base} while validating link"
+                f" for `{link.string}` in {doc.relative_to(root)!s}!"
+            )
+            total += 1
+    return total
+
+
+def check_reference_targets_exist(root: Path):
+    site_docs = {
+        p: BeautifulSoup(p.read_text("utf-8"), "html.parser")
+        for p in root.glob("**/*.html")
+    }
+    for doc, soup in site_docs.items():
+        for link in soup.find_all("a", attrs={"class": "reference internal"}):
+            base = link["href"].split("#")[0]
+            if any(base.startswith(s) for s in ("http://", "https://")):
+                continue
+            target_path = doc if base == "" else (doc.parent / base).resolve()
+            if target_path.is_dir():
+                target_path /= "index.html"
+            assert target_path.exists(), (
+                f"Target path {target_path!s} not found while validating"
+                f" link for `{link.string}` in {doc.relative_to(root)!s}!"
+            )
+
+
+def gather_ids(soup: BeautifulSoup) -> set:
+    """Gather all HTML IDs from a given page."""
+    return {tag["id"] for tag in soup.find_all(id=True)}

{sphinx_codeautolink-0.17.2 → sphinx_codeautolink-0.17.4}/tox.ini

@@ -35,7 +35,7 @@ commands = coverage run
 [testenv:doc8]
 description = Check documentation .rst files
 allowlist_externals = doc8
-commands = doc8 docs/src
+commands = doc8 docs/src --quiet
 
 [testenv:docs]
 description = Build Sphinx documentation
@@ -62,7 +62,7 @@ description = Build and check package
 deps = -r requirements/build
 allowlist_externals = rm, cmd
 commands =
-    python -m build
+    python -m build -C--quiet
     twine check --strict dist/*
 commands_post =
     lin,mac: rm -r dist
@@ -76,7 +76,7 @@ commands_pre =
     lin,mac: rm -rf dist
     win: cmd /c if exist dist rmdir /s /q dist
 commands =
-    python -m build
+    python -m build -C--quiet
     twine check --strict dist/*
     twine upload dist/* --config-file .pypirc
 commands_post =

sphinx_codeautolink-0.17.2/tests/extension/_check.py

@@ -1,41 +0,0 @@
-from pathlib import Path
-
-import requests
-from bs4 import BeautifulSoup
-
-# Cache external pages for the duration of the runtime,
-# so that we don't request them multiple times needlessly
-sess = requests.Session()
-external_site_ids = {}
-
-
-def check_link_targets(root: Path) -> int:
-    """Validate links in HTML site at root, return number of links found."""
-    site_docs = {
-        p.relative_to(root): BeautifulSoup(p.read_text("utf-8"), "html.parser")
-        for p in root.glob("**/*.html")
-    }
-    site_ids = {k: gather_ids(v) for k, v in site_docs.items()}
-
-    total = 0
-    for doc, soup in site_docs.items():
-        for link in soup.find_all("a", attrs={"class": "sphinx-codeautolink-a"}):
-            base, id_ = link["href"].split("#")
-            if any(base.startswith(s) for s in ("http://", "https://")):
-                if base not in external_site_ids:
-                    sub_soup = BeautifulSoup(sess.get(base).text, "html.parser")
-                    external_site_ids[base] = gather_ids(sub_soup)
-                ids = external_site_ids[base]
-            else:
-                ids = site_ids[Path(base)]
-            assert id_ in ids, (
-                f"ID {id_} not found in {base}"
-                f" while validating link for `{link.string}` in {doc!s}!"
-            )
-            total += 1
-    return total
-
-
-def gather_ids(soup: BeautifulSoup) -> set:
-    """Gather all HTML IDs from a given page."""
-    return {tag["id"] for tag in soup.find_all(id=True)}