sphinx-examples-as-code 0.2.0__tar.gz → 0.2.1__tar.gz

{sphinx_examples_as_code-0.2.0 → sphinx_examples_as_code-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.2.0
+Version: 0.2.1
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT

{sphinx_examples_as_code-0.2.0 → sphinx_examples_as_code-0.2.1}/sphinx_examples_as_code/__init__.py

@@ -494,15 +494,40 @@ def _examples_spans(doctree: nodes.document) -> list[tuple[nodes.Element, int, i
     return spans
 
 
+def _desc_id(desc: addnodes.desc) -> str | None:
+    """Pull the documented object's id (e.g. ``pkg.mod.func``) off a ``desc`` node."""
+    signature = desc.next_node(addnodes.desc_signature)
+    if signature is not None and signature.get('ids'):
+        return signature['ids'][0]
+    return None
+
+
 def _qualified_name_for(node: nodes.Node, docname: str, counter: int) -> str:
     """Best-effort identifier used to name the generated file and its title header."""
     ancestor: nodes.Node | None = node.parent
     while ancestor is not None:
         if isinstance(ancestor, addnodes.desc):
-            signature = ancestor.next_node(addnodes.desc_signature)
-            if signature is not None and signature.get('ids'):
-                return signature['ids'][0]
-        ancestor = ancestor.parent
+            desc_id = _desc_id(ancestor)
+            if desc_id is not None:
+                return desc_id
+        parent = ancestor.parent
+        if parent is not None:
+            # An "Examples" section written as a real RST heading (not a
+            # bare ``.. rubric::``) starts a new docutils section -- one
+            # can't nest inside the ``desc_content`` a numpydoc-rendered
+            # docstring builds it in, so it gets promoted to a sibling of
+            # the object's own ``desc`` node instead (same reason
+            # sphinx-gallery's own "# %%"-headed cells become siblings; see
+            # gallery mode's sibling-section handling). Look for the
+            # nearest ``desc`` immediately preceding it under that shared
+            # parent, closest first.
+            index = parent.index(ancestor)
+            for sibling in reversed(parent.children[:index]):
+                if isinstance(sibling, addnodes.desc):
+                    desc_id = _desc_id(sibling)
+                    if desc_id is not None:
+                        return desc_id
+        ancestor = parent
     base = Path(docname).name or docname
     return f'{base}-example-{counter}'
 

{sphinx_examples_as_code-0.2.0 → sphinx_examples_as_code-0.2.1}/sphinx_examples_as_code/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '0.2.1'
+__version_tuple__ = version_tuple = (0, 2, 1)
 
-__commit_id__ = commit_id = 'g5ead8d7ac'
+__commit_id__ = commit_id = 'g5224fa967'

{sphinx_examples_as_code-0.2.0 → sphinx_examples_as_code-0.2.1}/sphinx_examples_as_code.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.2.0
+Version: 0.2.1
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT

{sphinx_examples_as_code-0.2.0 → sphinx_examples_as_code-0.2.1}/sphinx_examples_as_code.egg-info/SOURCES.txt

@@ -15,12 +15,16 @@ sphinx_examples_as_code.egg-info/scm_file_list.json
 sphinx_examples_as_code.egg-info/scm_version.json
 sphinx_examples_as_code.egg-info/top_level.txt
 tests/test_gallery_downloads.py
+tests/test_single_function_page.py
 tests/test_sphinx_examples_as_code.py
 tests/test_tinypages.py
 tests/gallery_fixture/conf.py
 tests/gallery_fixture/index.rst
 tests/gallery_fixture/examples/GALLERY_HEADER.rst
 tests/gallery_fixture/examples/plot_minimal.py
+tests/single_function_fixture/conf.py
+tests/single_function_fixture/index.rst
+tests/single_function_fixture/mymodule.py
 tests/tinypages/conf.py
 tests/tinypages/docstring_cases.py
 tests/tinypages/docstring_cases.rst

{sphinx_examples_as_code-0.2.0 → sphinx_examples_as_code-0.2.1}/sphinx_examples_as_code.egg-info/scm_file_list.json

@@ -8,6 +8,7 @@
     ".github/release.yml",
     ".github/workflows/ci.yml",
     "tests/test_tinypages.py",
+    "tests/test_single_function_page.py",
     "tests/test_gallery_downloads.py",
     "tests/test_sphinx_examples_as_code.py",
     "tests/tinypages/index.rst",
@@ -18,6 +19,9 @@
     "tests/gallery_fixture/conf.py",
     "tests/gallery_fixture/examples/plot_minimal.py",
     "tests/gallery_fixture/examples/GALLERY_HEADER.rst",
+    "tests/single_function_fixture/index.rst",
+    "tests/single_function_fixture/conf.py",
+    "tests/single_function_fixture/mymodule.py",
     "sphinx_examples_as_code/__init__.py"
   ]
 }

{sphinx_examples_as_code-0.2.0 → sphinx_examples_as_code-0.2.1}/sphinx_examples_as_code.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.2.0",
+  "tag": "0.2.1",
   "distance": 0,
-  "node": "g5ead8d7ac522b8f558b03171296568d1bb3b8722",
+  "node": "g5224fa967500cbd885faa83213fd2a70aa717a21",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-05"

sphinx_examples_as_code-0.2.1/tests/single_function_fixture/conf.py

@@ -0,0 +1,84 @@
+"""Sphinx config reproducing a real-world numpydoc section-hoisting setup.
+
+numpydoc renders docstring sections (Notes, Examples, ...) as
+``.. rubric::`` by default, which never becomes a real docutils section --
+so ``_qualified_name_for``'s plain ancestor walk (desc_content -> desc)
+always finds the object's own ``desc`` node directly, no special handling
+needed. Some projects (pyvista's real docs included -- see its
+``doc/source/conf.py``) override this to get real headings for the page's
+"on this page" navbar, then hoist those sections out of the autodoc
+``desc`` node to page level so Sphinx's TocTreeCollector can see them. That
+lands "Examples" as a *sibling* of the object's own ``desc``, not an
+ancestor of its own heading -- the exact structure that produced a
+nonsensical ``<docname>-example-1`` header in production for a page that
+unambiguously documents one function.
+
+Reproduced here (rather than in ``tinypages/conf.py``) since it changes
+docstring-section rendering globally for the build it's applied to, and
+``tinypages`` is shared by many other tests that already pin exact output
+for the un-hoisted (rubric-based) case.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+
+from docutils import nodes
+from numpydoc.docscrape_sphinx import SphinxDocString
+from sphinx import addnodes
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+extensions = [
+    'numpydoc',
+    'sphinx.ext.autodoc',
+    'sphinx_examples_as_code',
+]
+
+root_doc = 'index'
+project = 'single_function_fixture'
+exclude_patterns = ['_build']
+numpydoc_show_class_members = False
+
+
+def _str_header(self, name):
+    return [name, '-' * len(name), '']
+
+
+SphinxDocString._str_header = _str_header
+
+
+def _is_nested_desc(node: nodes.Node) -> bool:
+    parent = node.parent
+    while parent is not None:
+        if isinstance(parent, addnodes.desc):
+            return True
+        parent = parent.parent
+    return False
+
+
+def _hoist_docstring_sections(app, doctree) -> None:
+    """Move docstring sections out of their ``desc`` node to page level."""
+    for desc in list(doctree.findall(addnodes.desc)):
+        if _is_nested_desc(desc):
+            continue
+        parent = desc.parent
+        if parent is None:
+            continue
+        # Only hoist when this object owns the page -- otherwise sections
+        # from several objects would collide at page level.
+        if len([node for node in parent if isinstance(node, addnodes.desc)]) != 1:
+            continue
+        content = next((node for node in desc if isinstance(node, addnodes.desc_content)), None)
+        if content is None:
+            continue
+        sections = [node for node in content if isinstance(node, nodes.section)]
+        index = parent.index(desc)
+        for offset, section in enumerate(sections):
+            content.remove(section)
+            parent.insert(index + 1 + offset, section)
+
+
+def setup(app):
+    app.connect('doctree-read', _hoist_docstring_sections)

sphinx_examples_as_code-0.2.1/tests/single_function_fixture/index.rst

@@ -0,0 +1,4 @@
+download_bunny
+==============
+
+.. autofunction:: mymodule.download_bunny

sphinx_examples_as_code-0.2.1/tests/single_function_fixture/mymodule.py

@@ -0,0 +1,13 @@
+"""Dummy module documented as a single-function page, like a real autosummary build."""
+
+from __future__ import annotations
+
+
+def download_bunny():
+    """Download bunny dataset.
+
+    Examples
+    --------
+    >>> import sys
+
+    """

sphinx_examples_as_code-0.2.1/tests/test_single_function_page.py

@@ -0,0 +1,40 @@
+"""Regression test for a real numpydoc "hoisted section" page structure.
+
+Builds a real sphinx site (not a hand-built doctree) using the same
+rubric-to-heading + section-hoisting setup pyvista's actual docs build uses
+(see ``single_function_fixture/conf.py``), confirming
+``_qualified_name_for`` names the download after the documented function
+rather than falling back to a nonsensical ``<docname>-example-1`` -- the
+exact bug seen in a real pyvista build for
+``pyvista.examples.downloads.download_bunny``.
+
+Complements the hand-built-doctree unit tests for ``_qualified_name_for``
+in ``test_sphinx_examples_as_code.py``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from test_tinypages import _run_sphinx_build
+from test_tinypages import _sphinx_build_cmd
+
+FIXTURE_DIR = Path(__file__).parent / 'single_function_fixture'
+
+
+def test_download_named_after_the_function_not_the_docname(tmp_path: Path):
+    html_dir = tmp_path / 'html'
+    doctree_dir = tmp_path / 'doctrees'
+    returncode, out, err = _run_sphinx_build(_sphinx_build_cmd(FIXTURE_DIR, html_dir, doctree_dir))
+    assert returncode == 0, f'sphinx build failed with stdout:\n{out}\nstderr:\n{err}\n'
+
+    downloads_dir = html_dir / '_downloads'
+    py_files = list(downloads_dir.rglob('*.py'))
+    assert len(py_files) == 1, f'expected exactly one generated .py, got {py_files}'
+    py_path = py_files[0]
+
+    # not "index-example-1" (the docname-derived fallback name)
+    assert py_path.stem == 'mymodule_download_bunny'
+
+    lines = py_path.read_text(encoding='utf-8').splitlines()
+    assert lines[0] == '# Examples from mymodule.download_bunny'

{sphinx_examples_as_code-0.2.0 → sphinx_examples_as_code-0.2.1}/tests/test_sphinx_examples_as_code.py

@@ -700,6 +700,46 @@ def test_qualified_name_for_desc_signature_without_ids_falls_back():
     assert seac._qualified_name_for(heading, 'mypage', 2) == 'mypage-example-2'
 
 
+def test_qualified_name_for_examples_section_sibling_of_desc():
+    r"""A real ``Examples\n--------`` heading, not a bare rubric.
+
+    Matches an actual numpydoc-rendered autosummary page: docutils can't
+    nest a new section inside the non-sectioning ``desc_content`` a
+    docstring's other fields render into, so it promotes "Examples" to a
+    section of its own, sitting as a *sibling* of the object's ``desc`` --
+    not an ancestor of the heading the way the plain-rubric case above is.
+    Confirmed against a real pyvista build, where this exact structure
+    produced a nonsensical ``<docname>-example-1`` header for a page that
+    unambiguously documents one function.
+    """
+    page_section = nodes.section()
+    page_section += nodes.title('', 'download_bunny')
+    desc = addnodes.desc()
+    desc += addnodes.desc_signature(ids=['pyvista.examples.downloads.download_bunny'])
+    page_section += desc
+    examples_section = nodes.section()
+    heading = nodes.title('', 'Examples')
+    examples_section += heading
+    page_section += examples_section
+
+    assert (
+        seac._qualified_name_for(heading, 'page', 1) == 'pyvista.examples.downloads.download_bunny'
+    )
+
+
+def test_qualified_name_for_examples_section_sibling_no_desc_falls_back():
+    # a promoted sibling section with nothing resembling a desc anywhere
+    # nearby -- e.g. a plain prose page's own "Examples\n--------" heading
+    page_section = nodes.section()
+    page_section += nodes.title('', 'Some Guide Page')
+    examples_section = nodes.section()
+    heading = nodes.title('', 'Examples')
+    examples_section += heading
+    page_section += examples_section
+
+    assert seac._qualified_name_for(heading, 'mypage', 4) == 'mypage-example-4'
+
+
 # ---------------------------------------------------------------------------
 # _header_segment
 # ---------------------------------------------------------------------------