sphinx-examples-as-code 0.4.1__tar.gz → 0.6.0__tar.gz

{sphinx_examples_as_code-0.4.1 → sphinx_examples_as_code-0.6.0}/.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
       with:
         persist-credentials: false
         fetch-depth: 0
-    - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9   # v9.0.0
+    - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4   # v10.1.0
       with:
         enable-cache: false
     - run: uv sync --group dev
@@ -43,10 +43,10 @@ jobs:
       with:
         persist-credentials: false
         fetch-depth: 0
-    - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9   # v9.0.0
+    - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4   # v10.1.0
       with:
         enable-cache: false
-    - uses: pyvista/setup-headless-display-action@5bc8de3bc71fcda7a96439571287a554901541a0   # v4.3
+    - uses: pyvista/setup-headless-display-action@c103a2ff45650d38cb71684b5dc6cdfeb9442c79   # v5.1.0
       with:
         pyvista: true
     - run: uv sync --group dev --python ${{ matrix.python-version }}
@@ -65,7 +65,7 @@ jobs:
       with:
         persist-credentials: false
         fetch-depth: 0
-    - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9   # v9.0.0
+    - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4   # v10.1.0
       with:
         enable-cache: false
     - run: uv build

{sphinx_examples_as_code-0.4.1 → sphinx_examples_as_code-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.4.1
+Version: 0.6.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,11 +106,8 @@ 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 bare `#` instead of a real blank line when
   that falls inside an admonition or a definition's own body in `.py`, so the whole
@@ -128,15 +117,19 @@ What happens to the content of an Examples section:
 - 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.
+- A table becomes an aligned text table, its caption on the line above: an RST simple
+  table in `.py`, a Markdown pipe table in `.ipynb`. Each cell is flattened to a single
+  line, and a column left entirely empty -- one holding only images, say -- is dropped
+  along with its heading.
 - 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
@@ -186,9 +179,10 @@ styles:
 
 Two things worth knowing before turning this on:
 
-- It's built against sphinx-gallery's own RST/HTML output (the same `sphx-glr-*` CSS
-  classes its own theming depends on), not a documented extension API. A future
-  sphinx-gallery release could shift that structure without warning.
+- It's built against sphinx-gallery's own doctree output — the `sphx-glr-*` CSS classes
+  its own theming depends on, and the private node type holding a highlighted code
+  block — not a documented extension API. A future sphinx-gallery release could shift
+  that structure without warning. Tested against sphinx-gallery 0.22 and later.
 - sphinx-gallery's own `.py`/`.ipynb`/`.zip` downloads still end up copied into
   `_downloads/`, even though nothing on the page links to them anymore.
 

{sphinx_examples_as_code-0.4.1 → sphinx_examples_as_code-0.6.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,11 +79,8 @@ 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 bare `#` instead of a real blank line when
   that falls inside an admonition or a definition's own body in `.py`, so the whole
@@ -101,15 +90,19 @@ What happens to the content of an Examples section:
 - 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.
+- A table becomes an aligned text table, its caption on the line above: an RST simple
+  table in `.py`, a Markdown pipe table in `.ipynb`. Each cell is flattened to a single
+  line, and a column left entirely empty -- one holding only images, say -- is dropped
+  along with its heading.
 - 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
@@ -159,9 +152,10 @@ styles:
 
 Two things worth knowing before turning this on:
 
-- It's built against sphinx-gallery's own RST/HTML output (the same `sphx-glr-*` CSS
-  classes its own theming depends on), not a documented extension API. A future
-  sphinx-gallery release could shift that structure without warning.
+- It's built against sphinx-gallery's own doctree output — the `sphx-glr-*` CSS classes
+  its own theming depends on, and the private node type holding a highlighted code
+  block — not a documented extension API. A future sphinx-gallery release could shift
+  that structure without warning. Tested against sphinx-gallery 0.22 and later.
 - sphinx-gallery's own `.py`/`.ipynb`/`.zip` downloads still end up copied into
   `_downloads/`, even though nothing on the page links to them anymore.
 

{sphinx_examples_as_code-0.4.1 → sphinx_examples_as_code-0.6.0}/pyproject.toml

@@ -11,7 +11,7 @@ dev = [
   'pytest-cov',
   'sphinx',
   'sphinx-design',
-  'sphinx-gallery>=0.21.0',
+  'sphinx-gallery>=0.22',
   'trame-pyvista',
 ]
 

{sphinx_examples_as_code-0.4.1 → sphinx_examples_as_code-0.6.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
@@ -92,6 +91,22 @@ _ADMONITION_LABELS = {
 
 _PYTHON_LANGUAGES = ('python', 'py', 'python3')
 
+# sphinx-gallery's own node type for a gallery example's Python code, in
+# place of a ``literal_block``: one child per pygments token, so that names
+# in the code can carry links to their documentation. Its language is spelled
+# ``lang``, and its source has to be read back off its children. Code in any
+# other language stays an ordinary ``literal_block``.
+#
+# Matched by tag name rather than by ``isinstance``: sphinx-gallery is not a
+# dependency of this extension (gallery support is opt-in via
+# ``gallery_downloads``), so the class itself can't be imported here.
+_GALLERY_CODE_BLOCK_TAGNAME = 'code_links_block'
+
+# Class on the ``inline`` nodes sphinx-gallery interleaves into the above when
+# the block has line numbers turned on. Rendering furniture, not source, so
+# they're dropped rather than baked into the generated file.
+_GALLERY_LINENOS_CLASS = 'linenos'
+
 # A chunk of generated lines tagged with how it should be spaced relative to
 # its neighbors when segments are joined (see ``_join_segments``):
 #   'code'      real Python source
@@ -154,9 +169,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 +246,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 +259,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.
@@ -328,16 +335,34 @@ def _convert_doctest_block(node: nodes.doctest_block) -> list[Segment]:
     return [('code', lines)]
 
 
-def _convert_literal_block(node: nodes.literal_block) -> list[Segment]:
+def _is_gallery_code_block(node: nodes.Node) -> bool:
+    """Check whether ``node`` is the node type sphinx-gallery puts example code in."""
+    return getattr(node, 'tagname', None) == _GALLERY_CODE_BLOCK_TAGNAME
+
+
+def _gallery_code_block_source(node: nodes.Element) -> str:
+    """Reassemble the source text sphinx-gallery split across per-token nodes."""
+    # One child per pygments token (some wrapped in a reference node), which
+    # ``astext()`` joins back together with no separator -- apart from the
+    # line-number nodes, which were never part of the source.
+    return ''.join(
+        child.astext() for child in node.children if not _has_class(child, _GALLERY_LINENOS_CLASS)
+    )
+
+
+def _convert_literal_block(node: nodes.Element) -> list[Segment]:
     """Convert a ``.. code-block::``. Python blocks stay code, others become comments."""
-    language = node.get('language', '')
+    if _is_gallery_code_block(node):
+        language, source = node.get('lang', ''), _gallery_code_block_source(node)
+    else:
+        language, source = node.get('language', ''), node.astext()
     # Case-insensitive: sphinx-gallery emits ``.. code-block:: Python`` (capitalized).
     if language.lower() in _PYTHON_LANGUAGES:
-        lines = [_clean_code_comment(line) for line in node.astext().splitlines()]
+        lines = [_clean_code_comment(line) for line in source.splitlines()]
         while lines and not lines[-1].strip():
             lines.pop()
         return [('code', lines)] if lines else []
-    text = node.astext().strip()
+    text = source.strip()
     if not text:
         return []
     comment_lines: list[str] = []
@@ -483,16 +508,125 @@ def _list_segment(
     return [('directive', lines)] if lines else []
 
 
+#: Narrowest a generated table column may be, per format.
+_TABLE_MIN_WIDTH = {'py': 1, 'ipynb': 3}
+
+
+def _table_cell_text(entry: nodes.entry, ctx: _RenderContext) -> str:
+    """Render one cell's content as a single line, list items separated by ``;``."""
+    parts: list[str] = []
+    for child in entry.children:
+        if isinstance(child, (nodes.bullet_list, nodes.enumerated_list)):
+            items = (_render_inline(item, ctx).strip() for item in child.children)
+            parts.append('; '.join(item for item in items if item))
+        else:
+            parts.append(_render_inline(child, ctx).strip())
+    return ' '.join(part for part in parts if part)
+
+
+def _table_rows(group: nodes.Element, ctx: _RenderContext) -> list[list[str]]:
+    """Render a ``thead``/``tbody``'s rows, padding a column-spanning cell with empties."""
+    rows: list[list[str]] = []
+    for row in group.children:
+        cells: list[str] = []
+        for entry in row.children:
+            cells.append(_table_cell_text(entry, ctx))
+            cells.extend([''] * entry.get('morecols', 0))
+        if any(cells):
+            rows.append(cells)
+    return rows
+
+
+def _table_grid(node: nodes.table, ctx: _RenderContext) -> tuple[list[list[str]], list[list[str]]]:
+    """Split a table into header rows and body rows, dropping any column left empty."""
+    head: list[list[str]] = []
+    body: list[list[str]] = []
+    for tgroup in node.children:
+        if not isinstance(tgroup, nodes.tgroup):
+            continue
+        for group in tgroup.children:
+            if isinstance(group, nodes.thead):
+                head.extend(_table_rows(group, ctx))
+            elif isinstance(group, nodes.tbody):
+                body.extend(_table_rows(group, ctx))
+    columns = max((len(row) for row in [*head, *body]), default=0)
+    for row in [*head, *body]:
+        row.extend([''] * (columns - len(row)))
+    filled = [index for index in range(columns) if any(row[index] for row in body)]
+    if not filled or len(filled) == columns:
+        return head, body
+    return (
+        [[row[index] for index in filled] for row in head],
+        [[row[index] for index in filled] for row in body],
+    )
+
+
+def _table_widths(rows: list[list[str]], minimum: int) -> list[int]:
+    """Measure each column, never narrower than ``minimum``."""
+    return [max(minimum, *map(len, column)) for column in zip(*rows, strict=True)]
+
+
+def _markdown_table_lines(head: list[list[str]], body: list[list[str]]) -> list[str]:
+    """Render rows as a Markdown pipe table, with a blank header row if there is none."""
+    head = [[cell.replace('|', r'\|') for cell in row] for row in head]
+    body = [[cell.replace('|', r'\|') for cell in row] for row in body]
+    widths = _table_widths([*head, *body], _TABLE_MIN_WIDTH['ipynb'])
+
+    def render(cells: list[str]) -> str:
+        padded = (cell.ljust(width) for cell, width in zip(cells, widths, strict=True))
+        return f'| {" | ".join(padded)} |'
+
+    header, *extra = head or [[''] * len(widths)]
+    divider = f'| {" | ".join("-" * width for width in widths)} |'
+    return [render(header), divider, *(render(cells) for cells in [*extra, *body])]
+
+
+def _simple_table_lines(head: list[list[str]], body: list[list[str]]) -> list[str]:
+    """Render rows as an RST simple table, bordered above, below and under its header."""
+    widths = _table_widths([*head, *body], _TABLE_MIN_WIDTH['py'])
+    border = '  '.join('=' * width for width in widths)
+
+    def render(cells: list[str]) -> str:
+        return '  '.join(
+            cell.ljust(width) for cell, width in zip(cells, widths, strict=True)
+        ).rstrip()
+
+    lines = [border]
+    for rows in (head, body):
+        if rows:
+            lines.extend(render(cells) for cells in rows)
+            lines.append(border)
+    return lines
+
+
+def _table_segment(node: nodes.table, ctx: _RenderContext) -> list[Segment]:
+    """Convert a table to an RST simple table in ``.py``, a Markdown one in ``.ipynb``.
+
+    Each cell is flattened to a single line, the caption sits above.
+    """
+    head, body = _table_grid(node, ctx)
+    if not head and not body:
+        return []
+    lines: list[str] = []
+    caption = next((child for child in node.children if isinstance(child, nodes.title)), None)
+    if caption is not None and (text := _render_inline(caption, ctx).strip()):
+        _add_comment(lines, text)
+        lines.append('#')
+    render = _markdown_table_lines if ctx.fmt == 'ipynb' else _simple_table_lines
+    for line in render(head, body):
+        _add_comment(lines, line)
+    return [('directive', lines)]
+
+
 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)]
 
@@ -505,19 +639,20 @@ def _convert_node(node: nodes.Node, ctx: _RenderContext) -> list[Segment]:
         return []
     if isinstance(node, nodes.doctest_block):
         return _convert_doctest_block(node)
-    if isinstance(node, nodes.literal_block):
+    if isinstance(node, nodes.literal_block) or _is_gallery_code_block(node):
         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)
@@ -536,6 +671,8 @@ def _convert_node(node: nodes.Node, ctx: _RenderContext) -> list[Segment]:
         return _definition_segment(node, ctx)
     if isinstance(node, (nodes.bullet_list, nodes.enumerated_list)):
         return _list_segment(node, ctx)
+    if isinstance(node, nodes.table):
+        return _table_segment(node, ctx)
     if isinstance(node, (*_CONTAINER_TYPES, nodes.section)):
         # nodes.section (gallery mode only): a sphinx-gallery ``# %%`` cell
         # with its own RST heading is a *sibling* section at the document
@@ -594,42 +731,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.
 
@@ -868,20 +969,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
@@ -896,7 +991,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``.
 
@@ -909,7 +1003,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):
@@ -930,9 +1024,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
@@ -958,14 +1050,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(
@@ -977,7 +1064,6 @@ def _process_span(
         formats,
         footer,
         link_labels,
-        include_see_also,
     )
     if not entries:
         return
@@ -1058,7 +1144,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.
 
@@ -1101,7 +1186,6 @@ def _process_gallery_page(
         formats,
         footer,
         link_labels,
-        include_see_also,
     )
     if not entries:
         return
@@ -1127,12 +1211,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)
@@ -1152,7 +1233,6 @@ def _process_doctree(app: Sphinx, doctree: nodes.document, docname: str) -> None
             formats,
             footer,
             link_labels,
-            include_see_also,
         )
 
 
@@ -1170,7 +1250,6 @@ _CONF_DEFAULTS: dict[str, object] = {
     'gallery_downloads': False,
     'footer': _DEFAULT_FOOTER,
     'link_labels': _DEFAULT_LINK_LABELS,
-    'include_see_also': True,
 }
 
 
@@ -1188,7 +1267,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.1 → sphinx_examples_as_code-0.6.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.1'
-__version_tuple__ = version_tuple = (0, 4, 1)
+__version__ = version = '0.6.0'
+__version_tuple__ = version_tuple = (0, 6, 0)
 
-__commit_id__ = commit_id = 'gfbf3dad3c'
+__commit_id__ = commit_id = 'g7280fbdd2'