sphinx-examples-as-code 0.4.0__tar.gz → 0.5.0__tar.gz

{sphinx_examples_as_code-0.4.0 → sphinx_examples_as_code-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.4.0
+Version: 0.5.0
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -66,7 +66,6 @@ sphinx_examples_as_code_conf = {
         'py': 'Download Python source code',
         'ipynb': 'Download Jupyter notebook',
     },
-    'include_see_also': True,
 }
 ```
 
@@ -76,13 +75,6 @@ sphinx_examples_as_code_conf = {
   (default). Always offered in that order regardless of how the list is written.
 - `link_labels`: the text of the download link(s) themselves, per format. Set only the
   format(s) you want to change; any left unset keep reading their own default shown above.
-- `include_see_also`: whether "See Also" content is included in the generated file.
-  `True` (default) includes it, in any of its forms: a `.. seealso::` admonition, a bare
-  `.. rubric:: See Also`, a hand-written `See Also` heading, or numpydoc's own "See Also"
-  field (including when it's been reordered outside the Examples section itself, or the
-  Examples section has been hoisted to a heading of its own — a setup some projects use to
-  get "Examples" listed in the page's own navigation). `False` excludes "See Also" content
-  in every one of those forms.
 - `gallery_downloads`: opt-in takeover of
   [sphinx-gallery](https://sphinx-gallery.github.io)'s own per-example downloads.
   `False` (default) leaves sphinx-gallery pages untouched. See
@@ -114,27 +106,26 @@ What happens to the content of an Examples section:
   real Python source. Doctest *output* lines are dropped — only the input code matters.
 - `.. code-block:: python` (or `py`) blocks are kept as-is; other languages become
   comments, set off with blank lines on both sides like any other directive.
-- Admonitions (`.. note::`, `.. warning::`, `.. seealso::`, ...) become a `# LABEL:`
-  comment followed by their content as comments, indented one level under the label in
-  `.py` only. "See Also" is recognized in any of its three forms (`.. seealso::`, a bare
-  `.. rubric:: See Also`, or a hand-written `See Also` heading) and always renders the
-  same way.
+- Admonitions (`.. note::`, `.. warning::`, ...) become a `# LABEL:` comment followed by
+  their content as comments, indented one level under the label in `.py` only.
 - A bullet/numbered list becomes a `-`/`N.`-marked line per item, set off with a blank
-  line on both sides in either format. A definition list's term stays at the surrounding
-  indent; its definition (the body nested under it) is indented one level further in
-  `.py`, same as an admonition's own content.
+  line on both sides in either format — a bare `#` instead of a real blank line when
+  that falls inside an admonition or a definition's own body in `.py`, so the whole
+  thing still reads as one unbroken comment block. A definition list's term stays at
+  the surrounding indent; its definition (the body nested under it) is indented one
+  level further in `.py`, same as an admonition's own content.
 - Cross-references and inline code (`:class:`, `:meth:`, `:func:`, `:attr:`,
   double-backtick literals, ...) keep their display text, wrapped in backticks (e.g.
   ``:class:`pyvista.Plotter` `` -> `` `pyvista.Plotter` ``). If `html_baseurl` is set and
-  the reference resolves: `.ipynb` turns it into a clickable link everywhere; `.py` only
-  writes the link inside a "See Also" part (as `name url` on its own line) — everywhere
-  else in `.py` the link is simply omitted.
+  the reference resolves, `.ipynb` turns it into a clickable link; `.py` never writes the
+  link, only the display text.
 - Plain prose-style references (`:ref:`, `:doc:`) are treated the same way, minus the
   backticks.
 - Everything else text-bearing (prose, captions, other non-Python code) becomes a plain
   `#` comment.
 - Figures/images, raw HTML, sphinx-design dropdowns/tab-sets, and sphinx-tags' `.. tags::`
   line are dropped entirely.
+- "See Also" content is always dropped.
 
 Generated `.py` files start with a `# Examples from <qualified name>` title header
 (gallery mode uses the page's own title instead -- see below), with a few whitespace

{sphinx_examples_as_code-0.4.0 → sphinx_examples_as_code-0.5.0}/README.md

@@ -39,7 +39,6 @@ sphinx_examples_as_code_conf = {
         'py': 'Download Python source code',
         'ipynb': 'Download Jupyter notebook',
     },
-    'include_see_also': True,
 }
 ```
 
@@ -49,13 +48,6 @@ sphinx_examples_as_code_conf = {
   (default). Always offered in that order regardless of how the list is written.
 - `link_labels`: the text of the download link(s) themselves, per format. Set only the
   format(s) you want to change; any left unset keep reading their own default shown above.
-- `include_see_also`: whether "See Also" content is included in the generated file.
-  `True` (default) includes it, in any of its forms: a `.. seealso::` admonition, a bare
-  `.. rubric:: See Also`, a hand-written `See Also` heading, or numpydoc's own "See Also"
-  field (including when it's been reordered outside the Examples section itself, or the
-  Examples section has been hoisted to a heading of its own — a setup some projects use to
-  get "Examples" listed in the page's own navigation). `False` excludes "See Also" content
-  in every one of those forms.
 - `gallery_downloads`: opt-in takeover of
   [sphinx-gallery](https://sphinx-gallery.github.io)'s own per-example downloads.
   `False` (default) leaves sphinx-gallery pages untouched. See
@@ -87,27 +79,26 @@ What happens to the content of an Examples section:
   real Python source. Doctest *output* lines are dropped — only the input code matters.
 - `.. code-block:: python` (or `py`) blocks are kept as-is; other languages become
   comments, set off with blank lines on both sides like any other directive.
-- Admonitions (`.. note::`, `.. warning::`, `.. seealso::`, ...) become a `# LABEL:`
-  comment followed by their content as comments, indented one level under the label in
-  `.py` only. "See Also" is recognized in any of its three forms (`.. seealso::`, a bare
-  `.. rubric:: See Also`, or a hand-written `See Also` heading) and always renders the
-  same way.
+- Admonitions (`.. note::`, `.. warning::`, ...) become a `# LABEL:` comment followed by
+  their content as comments, indented one level under the label in `.py` only.
 - A bullet/numbered list becomes a `-`/`N.`-marked line per item, set off with a blank
-  line on both sides in either format. A definition list's term stays at the surrounding
-  indent; its definition (the body nested under it) is indented one level further in
-  `.py`, same as an admonition's own content.
+  line on both sides in either format — a bare `#` instead of a real blank line when
+  that falls inside an admonition or a definition's own body in `.py`, so the whole
+  thing still reads as one unbroken comment block. A definition list's term stays at
+  the surrounding indent; its definition (the body nested under it) is indented one
+  level further in `.py`, same as an admonition's own content.
 - Cross-references and inline code (`:class:`, `:meth:`, `:func:`, `:attr:`,
   double-backtick literals, ...) keep their display text, wrapped in backticks (e.g.
   ``:class:`pyvista.Plotter` `` -> `` `pyvista.Plotter` ``). If `html_baseurl` is set and
-  the reference resolves: `.ipynb` turns it into a clickable link everywhere; `.py` only
-  writes the link inside a "See Also" part (as `name url` on its own line) — everywhere
-  else in `.py` the link is simply omitted.
+  the reference resolves, `.ipynb` turns it into a clickable link; `.py` never writes the
+  link, only the display text.
 - Plain prose-style references (`:ref:`, `:doc:`) are treated the same way, minus the
   backticks.
 - Everything else text-bearing (prose, captions, other non-Python code) becomes a plain
   `#` comment.
 - Figures/images, raw HTML, sphinx-design dropdowns/tab-sets, and sphinx-tags' `.. tags::`
   line are dropped entirely.
+- "See Also" content is always dropped.
 
 Generated `.py` files start with a `# Examples from <qualified name>` title header
 (gallery mode uses the page's own title instead -- see below), with a few whitespace

{sphinx_examples_as_code-0.4.0 → sphinx_examples_as_code-0.5.0}/sphinx_examples_as_code/__init__.py

@@ -7,7 +7,6 @@ from __future__ import annotations
 
 import ast
 from dataclasses import dataclass
-from dataclasses import replace
 import hashlib
 import json
 from pathlib import Path
@@ -154,9 +153,7 @@ class _RenderContext:
     app: Sphinx
     docname: str
     fmt: str  # 'py' or 'ipynb'
-    in_see_also: bool = False
     in_footer: bool = False
-    show_see_also: bool = True
 
 
 def _normalized_html_baseurl(app: Sphinx) -> str | None:
@@ -233,9 +230,8 @@ def _render_reference(node: nodes.reference, ctx: _RenderContext) -> str:
     """Render a resolved or unresolved cross-reference/hyperlink.
 
     The target URL, if resolved, is used as a clickable markdown link in
-    notebooks (always), and as literal URL text in ``.py`` (only within a
-    "See Also" part or the footer -- elsewhere in ``.py`` the link is simply
-    omitted).
+    notebooks (always), and as literal URL text in ``.py`` (only within the
+    footer -- elsewhere in ``.py`` the link is simply omitted).
     """
     display = node.astext()
     is_code = any(isinstance(child, nodes.literal) for child in node.children)
@@ -247,11 +243,6 @@ def _render_reference(node: nodes.reference, ctx: _RenderContext) -> str:
     if ctx.fmt == 'ipynb':
         return f'[`{display}`]({url})' if is_code else f'[{display}]({url})'
 
-    if ctx.in_see_also:
-        # Surrounding newlines set this off on its own line; _add_comment
-        # splits on them like any other multi-line text.
-        return f'\n{display} {url}\n'
-
     if ctx.in_footer:
         # Inline, not surrounded by newlines -- "text url" in place, not a
         # markdown link.
@@ -403,6 +394,34 @@ def _indent_comment_line(line: str) -> str:
     return f'# {_ADMONITION_CONTENT_INDENT}{line.removeprefix("# ")}'
 
 
+def _is_raw_code_line(line: str) -> bool:
+    """Check whether a rendered ``.py`` line is real code, not a ``#`` comment line."""
+    return bool(line) and not line.startswith('#')
+
+
+def _fill_comment_gaps(lines: list[str]) -> list[str]:
+    """Turn a blank separator line into a bare ``#`` unless it borders raw code.
+
+    ``_join_segments`` forces a blank line around some segment boundaries
+    (e.g. a paragraph followed by a nested list) meant to visually separate
+    unrelated top-level content. Folded into one ``# LABEL:`` comment block
+    instead (see ``_indent_label_content``/``_definition_segment``), that
+    same blank line needs a ``#`` to still read as part of that one block.
+    A blank line bordering a raw code line (left flush and uncommented --
+    see ``_convert_node``'s doctest/literal-block handling) stays blank,
+    since that boundary really is between code and comment.
+    """
+    result: list[str] = []
+    for i, line in enumerate(lines):
+        if line != '':
+            result.append(line)
+            continue
+        before = lines[i - 1] if i > 0 else ''
+        after = lines[i + 1] if i + 1 < len(lines) else ''
+        result.append(line if _is_raw_code_line(before) or _is_raw_code_line(after) else '#')
+    return result
+
+
 def _indent_label_content(lines: list[str], fmt: str) -> list[str]:
     """Indent every line after the first (a ``# LABEL:`` line) under it.
 
@@ -410,7 +429,8 @@ def _indent_label_content(lines: list[str], fmt: str) -> list[str]:
     """
     if fmt != 'py' or not lines:
         return lines
-    return [lines[0], *(_indent_comment_line(line) for line in lines[1:])]
+    label, *rest = _fill_comment_gaps(lines)
+    return [label, *(_indent_comment_line(line) for line in rest)]
 
 
 def _definition_segment(node: nodes.definition, ctx: _RenderContext) -> list[Segment]:
@@ -423,7 +443,7 @@ def _definition_segment(node: nodes.definition, ctx: _RenderContext) -> list[Seg
         segments.extend(_convert_node(child, ctx))
     lines = _join_segments(segments)
     if ctx.fmt == 'py':
-        lines = [_indent_comment_line(line) for line in lines]
+        lines = [_indent_comment_line(line) for line in _fill_comment_gaps(lines)]
     return [('text', lines)] if lines else []
 
 
@@ -458,12 +478,11 @@ def _convert_admonition(
     node: nodes.Element, label: str, ctx: _RenderContext, *, skip_first_title: bool = False
 ) -> list[Segment]:
     """Convert an admonition-like container to a ``# LABEL:`` directive segment."""
-    inner_ctx = replace(ctx, in_see_also=True) if label.upper() == 'SEE ALSO' else ctx
     inner: list[Segment] = [('text', [f'# {label}:'])]
     for child in node.children:
         if skip_first_title and isinstance(child, nodes.title):
             continue
-        inner.extend(_convert_node(child, inner_ctx))
+        inner.extend(_convert_node(child, ctx))
     lines = _indent_label_content(_join_segments(inner), ctx.fmt)
     return [('directive', lines)]
 
@@ -479,16 +498,17 @@ def _convert_node(node: nodes.Node, ctx: _RenderContext) -> list[Segment]:
     if isinstance(node, nodes.literal_block):
         return _convert_literal_block(node)
     if type(node) in _ADMONITION_LABELS:
-        if _is_see_also_type(node) and not ctx.show_see_also:
+        if _is_see_also_type(node):
+            # "See Also" content is always dropped -- see _build_segments
+            # for the bare-rubric form and _is_see_also_section below for
+            # the hand-written-heading form.
             return []
         return _convert_admonition(node, _ADMONITION_LABELS[type(node)], ctx)
     if _is_see_also_section(node):
         # a hand-written "See Also\n--------" heading nests as a full
-        # section rather than a flat sibling - treat it like the
-        # ``.. seealso::`` directive it's standing in for.
-        if not ctx.show_see_also:
-            return []
-        return _convert_admonition(node, 'SEE ALSO', ctx, skip_first_title=True)
+        # section rather than a flat sibling - dropped the same as any
+        # other "See Also" form.
+        return []
     if isinstance(node, nodes.admonition):
         # generic ``.. admonition:: Custom Title`` - use its own title as the label
         title_node = node.next_node(nodes.title)
@@ -565,42 +585,6 @@ def _is_see_also_type(node: nodes.Node) -> bool:
     return type(node) in _ADMONITION_LABELS and _ADMONITION_LABELS[type(node)] == 'SEE ALSO'
 
 
-def _see_also_in_desc_content(desc: addnodes.desc) -> nodes.Node | None:
-    """Find a "See Also" admonition-type node among a ``desc`` node's own ``desc_content``."""
-    content = next(
-        (child for child in desc.children if isinstance(child, addnodes.desc_content)), None
-    )
-    if content is None:
-        return None
-    return next((child for child in content.children if _is_see_also_type(child)), None)
-
-
-def _find_external_see_also(
-    parent: nodes.Element, start: int, end: int, heading: nodes.Node
-) -> nodes.Node | None:
-    """Find a "See Also" part sited outside the normal ``[start, end)`` span.
-
-    numpydoc's own "See Also" field is canonically reordered to sit before
-    "Examples", as a sibling under ``parent``. If "Examples" was written as
-    a real RST heading and hoisted out of its own ``desc_content`` to page
-    level (see ``_enclosing_descs``), "See Also" -- not a ``nodes.section``,
-    so untouched by that hoisting -- stays behind there instead, in the
-    ``desc_content`` of the one ``desc`` that used to contain this heading.
-    Only that nearest enclosing ``desc`` is checked -- not every one
-    ``_enclosing_descs`` yields -- or a page listing several documented
-    objects in a row would leak one object's "See Also" onto another's.
-    """
-    for i, child in enumerate(parent.children):
-        if start <= i < end:
-            continue
-        if _is_see_also_type(child):
-            return child
-    desc = next(_enclosing_descs(heading), None)
-    if desc is not None:
-        return _see_also_in_desc_content(desc)
-    return None
-
-
 def _examples_spans(doctree: nodes.document) -> list[tuple[nodes.Element, int, int, nodes.Node]]:
     """Find every "Examples" heading's content span.
 
@@ -839,20 +823,14 @@ def _build_segments(nodes_in_span: list[nodes.Node], ctx: _RenderContext) -> lis
     """Convert a span's nodes into segments.
 
     A bare ``.. rubric:: See Also`` heading isn't wrapped in a container the
-    way ``.. seealso::`` or a nested section are: everything after it gets
-    gathered into one merged directive segment instead.
+    way ``.. seealso::`` or a nested section are, so everything after it is
+    just as much "See Also" content as the heading itself, with no node of
+    its own marking where it ends -- dropping the heading and stopping
+    there drops all of it.
     """
     segments: list[Segment] = []
-    for i, node in enumerate(nodes_in_span):
+    for node in nodes_in_span:
         if isinstance(node, nodes.rubric) and _is_see_also_heading(node):
-            if not ctx.show_see_also:
-                break
-            inner_ctx = replace(ctx, in_see_also=True)
-            inner: list[Segment] = [('text', ['# SEE ALSO:'])]
-            for later_node in nodes_in_span[i + 1 :]:
-                inner.extend(_convert_node(later_node, inner_ctx))
-            lines = _indent_label_content(_join_segments(inner), ctx.fmt)
-            segments.append(('directive', lines))
             break
         segments.extend(_convert_node(node, ctx))
     return segments
@@ -867,7 +845,6 @@ def _build_download_entries(
     formats: list[str],
     footer: str | None,
     link_labels: dict[str, str],
-    include_see_also: bool,
 ) -> list[tuple[str, str]]:
     """Convert a span of nodes into written ``.py``/``.ipynb`` files, per ``formats``.
 
@@ -880,7 +857,7 @@ def _build_download_entries(
     file's own header is the one heading every generated file has exactly
     one of (see ``_title_underline_segment``).
     """
-    py_ctx = _RenderContext(app=app, docname=docname, fmt='py', show_see_also=include_see_also)
+    py_ctx = _RenderContext(app=app, docname=docname, fmt='py')
     py_segments = _build_segments(nodes_in_span, py_ctx)
 
     if not any(kind == 'code' for kind, _lines in py_segments):
@@ -901,9 +878,7 @@ def _build_download_entries(
         if fmt == 'py':
             rel_path = _write_source(app, name, source)
         else:
-            ipynb_ctx = _RenderContext(
-                app=app, docname=docname, fmt='ipynb', show_see_also=include_see_also
-            )
+            ipynb_ctx = _RenderContext(app=app, docname=docname, fmt='ipynb')
             ipynb_segments = _build_segments(nodes_in_span, ipynb_ctx)
             ipynb_header = _title_underline_segment(header_title, 1, 'ipynb')
             # Converted separately from the footer and concatenated, rather
@@ -929,14 +904,9 @@ def _process_span(
     formats: list[str],
     footer: str | None,
     link_labels: dict[str, str],
-    include_see_also: bool,
 ) -> None:
     """Convert one Examples span and insert download link(s) if it has real code."""
     nodes_in_span = list(parent.children[start:end])
-    if include_see_also:
-        external_see_also = _find_external_see_also(parent, start, end, heading)
-        if external_see_also is not None:
-            nodes_in_span.append(external_see_also)
 
     name = _qualified_name_for(heading, docname, counter)
     entries = _build_download_entries(
@@ -948,7 +918,6 @@ def _process_span(
         formats,
         footer,
         link_labels,
-        include_see_also,
     )
     if not entries:
         return
@@ -1029,7 +998,6 @@ def _process_gallery_page(
     formats: list[str],
     footer: str | None,
     link_labels: dict[str, str],
-    include_see_also: bool,
 ) -> None:
     """Replace a sphinx-gallery page's own download footer with converted downloads.
 
@@ -1072,7 +1040,6 @@ def _process_gallery_page(
         formats,
         footer,
         link_labels,
-        include_see_also,
     )
     if not entries:
         return
@@ -1098,12 +1065,9 @@ def _process_doctree(app: Sphinx, doctree: nodes.document, docname: str) -> None
     formats = conf['formats']
     footer = conf['footer']
     link_labels = conf['link_labels']
-    include_see_also = conf['include_see_also']
 
     if conf['gallery_downloads']:
-        _process_gallery_page(
-            app, docname, doctree, position, formats, footer, link_labels, include_see_also
-        )
+        _process_gallery_page(app, docname, doctree, position, formats, footer, link_labels)
 
     # Process spans per shared parent, last to first.
     spans = _examples_spans(doctree)
@@ -1123,7 +1087,6 @@ def _process_doctree(app: Sphinx, doctree: nodes.document, docname: str) -> None
             formats,
             footer,
             link_labels,
-            include_see_also,
         )
 
 
@@ -1141,7 +1104,6 @@ _CONF_DEFAULTS: dict[str, object] = {
     'gallery_downloads': False,
     'footer': _DEFAULT_FOOTER,
     'link_labels': _DEFAULT_LINK_LABELS,
-    'include_see_also': True,
 }
 
 
@@ -1159,7 +1121,7 @@ def _coerce_conf_value(key: str, value: object) -> object:
         return value
     if key == 'formats':
         return value.split(',')
-    if key in ('gallery_downloads', 'include_see_also'):
+    if key == 'gallery_downloads':
         if value == '0':
             return False
         if value == '1':

{sphinx_examples_as_code-0.4.0 → sphinx_examples_as_code-0.5.0}/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.4.0'
-__version_tuple__ = version_tuple = (0, 4, 0)
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)
 
-__commit_id__ = commit_id = 'ge8e70c9b9'
+__commit_id__ = commit_id = 'g7bd70a33e'

{sphinx_examples_as_code-0.4.0 → sphinx_examples_as_code-0.5.0}/sphinx_examples_as_code.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.4.0
+Version: 0.5.0
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -66,7 +66,6 @@ sphinx_examples_as_code_conf = {
         'py': 'Download Python source code',
         'ipynb': 'Download Jupyter notebook',
     },
-    'include_see_also': True,
 }
 ```
 
@@ -76,13 +75,6 @@ sphinx_examples_as_code_conf = {
   (default). Always offered in that order regardless of how the list is written.
 - `link_labels`: the text of the download link(s) themselves, per format. Set only the
   format(s) you want to change; any left unset keep reading their own default shown above.
-- `include_see_also`: whether "See Also" content is included in the generated file.
-  `True` (default) includes it, in any of its forms: a `.. seealso::` admonition, a bare
-  `.. rubric:: See Also`, a hand-written `See Also` heading, or numpydoc's own "See Also"
-  field (including when it's been reordered outside the Examples section itself, or the
-  Examples section has been hoisted to a heading of its own — a setup some projects use to
-  get "Examples" listed in the page's own navigation). `False` excludes "See Also" content
-  in every one of those forms.
 - `gallery_downloads`: opt-in takeover of
   [sphinx-gallery](https://sphinx-gallery.github.io)'s own per-example downloads.
   `False` (default) leaves sphinx-gallery pages untouched. See
@@ -114,27 +106,26 @@ What happens to the content of an Examples section:
   real Python source. Doctest *output* lines are dropped — only the input code matters.
 - `.. code-block:: python` (or `py`) blocks are kept as-is; other languages become
   comments, set off with blank lines on both sides like any other directive.
-- Admonitions (`.. note::`, `.. warning::`, `.. seealso::`, ...) become a `# LABEL:`
-  comment followed by their content as comments, indented one level under the label in
-  `.py` only. "See Also" is recognized in any of its three forms (`.. seealso::`, a bare
-  `.. rubric:: See Also`, or a hand-written `See Also` heading) and always renders the
-  same way.
+- Admonitions (`.. note::`, `.. warning::`, ...) become a `# LABEL:` comment followed by
+  their content as comments, indented one level under the label in `.py` only.
 - A bullet/numbered list becomes a `-`/`N.`-marked line per item, set off with a blank
-  line on both sides in either format. A definition list's term stays at the surrounding
-  indent; its definition (the body nested under it) is indented one level further in
-  `.py`, same as an admonition's own content.
+  line on both sides in either format — a bare `#` instead of a real blank line when
+  that falls inside an admonition or a definition's own body in `.py`, so the whole
+  thing still reads as one unbroken comment block. A definition list's term stays at
+  the surrounding indent; its definition (the body nested under it) is indented one
+  level further in `.py`, same as an admonition's own content.
 - Cross-references and inline code (`:class:`, `:meth:`, `:func:`, `:attr:`,
   double-backtick literals, ...) keep their display text, wrapped in backticks (e.g.
   ``:class:`pyvista.Plotter` `` -> `` `pyvista.Plotter` ``). If `html_baseurl` is set and
-  the reference resolves: `.ipynb` turns it into a clickable link everywhere; `.py` only
-  writes the link inside a "See Also" part (as `name url` on its own line) — everywhere
-  else in `.py` the link is simply omitted.
+  the reference resolves, `.ipynb` turns it into a clickable link; `.py` never writes the
+  link, only the display text.
 - Plain prose-style references (`:ref:`, `:doc:`) are treated the same way, minus the
   backticks.
 - Everything else text-bearing (prose, captions, other non-Python code) becomes a plain
   `#` comment.
 - Figures/images, raw HTML, sphinx-design dropdowns/tab-sets, and sphinx-tags' `.. tags::`
   line are dropped entirely.
+- "See Also" content is always dropped.
 
 Generated `.py` files start with a `# Examples from <qualified name>` title header
 (gallery mode uses the page's own title instead -- see below), with a few whitespace

sphinx_examples_as_code-0.5.0/sphinx_examples_as_code.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.5.0",
+  "distance": 0,
+  "node": "g7bd70a33e84d064efda810292fbddfbbe32209bb",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-08-20"
+}

{sphinx_examples_as_code-0.4.0 → sphinx_examples_as_code-0.5.0}/tests/test_single_function_page.py

@@ -38,37 +38,3 @@ def test_download_named_after_the_function_not_the_docname(tmp_path: Path):
 
     lines = py_path.read_text(encoding='utf-8').splitlines()
     assert lines[0] == '# Examples from mymodule.download_bunny'
-
-
-def test_hoisted_see_also_field_included_by_default(tmp_path: Path):
-    # numpydoc's own "See Also" field is never itself a section, so the
-    # hoisting that moves "Examples" out to page level (see conf.py) leaves
-    # "See Also" behind in the object's own desc_content -- orphaned from
-    # the heading unless _find_external_see_also looks there too.
-    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'
-
-    py_path = next((html_dir / '_downloads').rglob('*.py'))
-    content = py_path.read_text(encoding='utf-8')
-    assert '# SEE ALSO:' in content
-    assert 'Download bunny dataset.' in content.split('# SEE ALSO:')[1]
-
-
-def test_hoisted_see_also_field_excluded_when_disabled(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,
-            ('-D', 'sphinx_examples_as_code_conf.include_see_also=0'),
-        ),
-    )
-    assert returncode == 0, f'sphinx build failed with stdout:\n{out}\nstderr:\n{err}\n'
-
-    py_path = next((html_dir / '_downloads').rglob('*.py'))
-    content = py_path.read_text(encoding='utf-8')
-    assert '# SEE ALSO:' not in content