sphinx-examples-as-code 0.3.1__tar.gz → 0.3.3__tar.gz

{sphinx_examples_as_code-0.3.1 → sphinx_examples_as_code-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.3.1
+Version: 0.3.3
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -107,9 +107,11 @@ What happens to the content of an Examples section:
 - `.. 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. "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.
+  comment followed by their content as comments, indented one level under the label in
+  `.py` (not `.ipynb`, where leading whitespace within a paragraph has no visible effect
+  once rendered). "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.
 - 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
@@ -154,14 +156,21 @@ Detection is automatic and per-page — any page without a sphinx-gallery downlo
 is left completely untouched. Gallery pages and ordinary docstring/prose pages (using
 the Examples-section behavior above) can coexist on the same site.
 
-A `# %%` cell with its own RST heading gets the same title-plus-underline treatment as
-the file's own header, and renders as a real Markdown heading in `.ipynb`. Level is
-relative to actual RST section nesting, not always one below the file's own header:
-level 1 (`<h1>`, `# Title` + `# ====`) for the file's own header, or a cell heading that
-reuses the page title's own underline character; level 2 (`<h2>`, `# Title` + `# ----`)
-for a cell heading nested under it (the common case), or one level below whatever
-heading precedes it. Level 3 and deeper use ATX syntax instead (`# ### Title`), since
-Markdown's underline-style headings only support two levels.
+A `# %%` cell with its own RST heading gets the same header treatment as the file's own
+title, and renders as a real Markdown heading in `.ipynb`. Level is relative to actual
+RST section nesting, not always one below the file's own header: a cell heading nested
+under the page's own title (the common case) is one level below it; one that reuses the
+page title's own underline character is level 1, the same as the file's own header; a
+cell heading nested under *that* is level 2 relative to it, and so on.
+
+Each format uses one heading style consistently across every level, rather than mixing
+styles:
+
+- `.py` uses an RST-style title + underline, one character per level -- the same
+  sequence Sphinx's own documentation uses for sections through sub-paragraphs: `=`, `-`,
+  `~`, `^`, `"`, `'` for levels 1 through 6.
+- `.ipynb` always uses ATX syntax (`#`, `##`, `###`, ...), since that's a real Markdown
+  heading at any level, whereas an underline only reads as one for the first two.
 
 Two things worth knowing before turning this on:
 

{sphinx_examples_as_code-0.3.1 → sphinx_examples_as_code-0.3.3}/README.md

@@ -80,9 +80,11 @@ What happens to the content of an Examples section:
 - `.. 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. "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.
+  comment followed by their content as comments, indented one level under the label in
+  `.py` (not `.ipynb`, where leading whitespace within a paragraph has no visible effect
+  once rendered). "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.
 - 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
@@ -127,14 +129,21 @@ Detection is automatic and per-page — any page without a sphinx-gallery downlo
 is left completely untouched. Gallery pages and ordinary docstring/prose pages (using
 the Examples-section behavior above) can coexist on the same site.
 
-A `# %%` cell with its own RST heading gets the same title-plus-underline treatment as
-the file's own header, and renders as a real Markdown heading in `.ipynb`. Level is
-relative to actual RST section nesting, not always one below the file's own header:
-level 1 (`<h1>`, `# Title` + `# ====`) for the file's own header, or a cell heading that
-reuses the page title's own underline character; level 2 (`<h2>`, `# Title` + `# ----`)
-for a cell heading nested under it (the common case), or one level below whatever
-heading precedes it. Level 3 and deeper use ATX syntax instead (`# ### Title`), since
-Markdown's underline-style headings only support two levels.
+A `# %%` cell with its own RST heading gets the same header treatment as the file's own
+title, and renders as a real Markdown heading in `.ipynb`. Level is relative to actual
+RST section nesting, not always one below the file's own header: a cell heading nested
+under the page's own title (the common case) is one level below it; one that reuses the
+page title's own underline character is level 1, the same as the file's own header; a
+cell heading nested under *that* is level 2 relative to it, and so on.
+
+Each format uses one heading style consistently across every level, rather than mixing
+styles:
+
+- `.py` uses an RST-style title + underline, one character per level -- the same
+  sequence Sphinx's own documentation uses for sections through sub-paragraphs: `=`, `-`,
+  `~`, `^`, `"`, `'` for levels 1 through 6.
+- `.ipynb` always uses ATX syntax (`#`, `##`, `###`, ...), since that's a real Markdown
+  heading at any level, whereas an underline only reads as one for the first two.
 
 Two things worth knowing before turning this on:
 

{sphinx_examples_as_code-0.3.1 → sphinx_examples_as_code-0.3.3}/sphinx_examples_as_code/__init__.py

@@ -368,29 +368,31 @@ def _convert_literal_block(node: nodes.literal_block) -> list[Segment]:
     return [('directive', comment_lines)]
 
 
-#: Setext underline character for the two levels it supports -- ``=`` for
-#: the file's own top-level header (level 1), ``-`` for a subheading
-#: (level 2). Anything deeper uses ATX ``#`` syntax instead (see
-#: ``_title_underline_segment``).
-_TITLE_UNDERLINE_CHARS = {1: '=', 2: '-'}
+#: RST underline character per heading level, for ``.py`` output -- the
+#: same sequence Sphinx's own documentation uses for sections, subsections,
+#: subsubsections, paragraphs, and sub-paragraphs.
+_TITLE_UNDERLINE_CHARS = {1: '=', 2: '-', 3: '~', 4: '^', 5: '"', 6: "'"}
 
+#: Deepest heading level either heading style below can represent.
+_MAX_HEADING_LEVEL = 6
 
-def _title_underline_segment(title: str, level: int = 1) -> Segment:
+
+def _title_underline_segment(title: str, level: int, fmt: str) -> Segment:
     """Build a heading directive segment for ``title`` at the given level.
 
-    Levels 1 and 2 use a setext-style title + underline (e.g. ``# Title`` +
-    ``# =====``), matching the file's own header (see ``_header_segment``)
-    and gallery mode's sibling-section headings respectively. Level 3+ uses
-    ATX ``#`` syntax instead (e.g. ``# ### Title``), since CommonMark's
-    setext syntax only supports the first two levels. Either way, this is
-    what makes the heading render as real Markdown in ``.ipynb`` (once the
-    ``#`` comment prefix is stripped for markdown cells) rather than plain
-    text.
+    Consistent within each format rather than mixed: ``.py`` always uses an
+    RST-style title + underline (e.g. ``# Title`` + ``# =====``), one
+    character per level (see ``_TITLE_UNDERLINE_CHARS``); ``.ipynb`` always
+    uses ATX ``#`` syntax instead (e.g. ``# ### Title``), since that's a
+    real Markdown heading at any level once the ``#`` comment prefix is
+    stripped for markdown cells, whereas an RST-style underline only reads
+    as a heading there for the first two levels.
     """
-    if level <= 2:
-        underline = _TITLE_UNDERLINE_CHARS[level] * len(title)
-        return ('directive', [f'# {title}', f'# {underline}'])
-    return ('directive', [f'# {"#" * level} {title}'])
+    level = min(level, _MAX_HEADING_LEVEL)
+    if fmt == 'ipynb':
+        return ('directive', [f'# {"#" * level} {title}'])
+    underline = _TITLE_UNDERLINE_CHARS[level] * len(title)
+    return ('directive', [f'# {title}', f'# {underline}'])
 
 
 def _heading_level(title: nodes.title) -> int:
@@ -399,15 +401,44 @@ def _heading_level(title: nodes.title) -> int:
     Counts the title's own section and each ancestor ``nodes.section``.
     Running this on the file's own header would give level 1; a title
     nested inside that comes out level 2, one nested inside that comes out
-    level 3, and so on -- clamped to 6, the deepest level CommonMark's ATX
-    heading syntax can represent.
+    level 3, and so on -- clamped to ``_MAX_HEADING_LEVEL``.
     """
     level = 0
     node: nodes.Node | None = title.parent
     while isinstance(node, nodes.section):
         level += 1
         node = node.parent
-    return min(level, 6)
+    return min(level, _MAX_HEADING_LEVEL)
+
+
+#: Extra indent for an admonition's content, under its ``# LABEL:`` line --
+#: ``.py`` only (see ``_convert_admonition``).
+_ADMONITION_CONTENT_INDENT = '    '
+
+
+def _indent_comment_line(line: str) -> str:
+    """Indent a ``# text`` comment line's content by ``_ADMONITION_CONTENT_INDENT``.
+
+    A bare ``#`` (blank line within a comment block) or a blank separator
+    line (``''``) has no content to indent, so both pass through unchanged
+    -- as does a raw code line (no ``#`` prefix at all), left alone so
+    indenting an admonition's content never touches real Python source.
+    """
+    if not line.startswith('# '):
+        return line
+    return f'# {_ADMONITION_CONTENT_INDENT}{line.removeprefix("# ")}'
+
+
+def _indent_label_content(lines: list[str], fmt: str) -> list[str]:
+    """Indent every line after the first (a ``# LABEL:`` line) under it.
+
+    ``.py`` only: in ``.ipynb``, once rendered as markdown, leading
+    whitespace within a paragraph collapses to nothing (confirmed against a
+    real CommonMark parse), so it would be invisible there anyway.
+    """
+    if fmt != 'py' or not lines:
+        return lines
+    return [lines[0], *(_indent_comment_line(line) for line in lines[1:])]
 
 
 def _convert_admonition(
@@ -420,7 +451,8 @@ def _convert_admonition(
         if skip_first_title and isinstance(child, nodes.title):
             continue
         inner.extend(_convert_node(child, inner_ctx))
-    return [('directive', _join_segments(inner))]
+    lines = _indent_label_content(_join_segments(inner), ctx.fmt)
+    return [('directive', lines)]
 
 
 def _convert_node(node: nodes.Node, ctx: _RenderContext) -> list[Segment]:
@@ -453,7 +485,7 @@ def _convert_node(node: nodes.Node, ctx: _RenderContext) -> list[Segment]:
         # _heading_level).
         title_text = _render_inline(node, ctx).strip()
         level = _heading_level(node)
-        return [_title_underline_segment(title_text, level=level)] if title_text else []
+        return [_title_underline_segment(title_text, level, ctx.fmt)] if title_text else []
     if isinstance(node, (*_CONTAINER_TYPES, nodes.section)):
         # nodes.section (gallery mode only): a sphinx-gallery ``# %%`` cell
         # with its own RST heading becomes a *sibling* section at the
@@ -577,9 +609,9 @@ def _qualified_name_for(node: nodes.Node, docname: str, counter: int) -> str:
     return f'{base}-example-{counter}'
 
 
-def _header_segment(qualified_name: str) -> Segment:
-    """Build the title-header segment, e.g. ``# pyvista.read examples`` + underline."""
-    return _title_underline_segment(f'Examples from {qualified_name}')
+def _header_title(qualified_name: str) -> str:
+    """Build the file's own header title text, e.g. ``Examples from pyvista.read``."""
+    return f'Examples from {qualified_name}'
 
 
 # A plain divider, not tied to any specific text's length the way a title
@@ -596,8 +628,8 @@ def _footer_segment(footer: str | None, fmt: str, app: Sphinx, docname: str) ->
     """Build the footer directive segment, if a footer is configured.
 
     Empty (0 or 1 elements, not a bare ``Segment | None``) so callers can
-    just splat it into a segment list like ``_header_segment``'s result.
-    Starts with ``_FOOTER_SEPARATOR`` -- see its comment for why.
+    just splat it into a segment list. Starts with ``_FOOTER_SEPARATOR``
+    -- see its comment for why.
 
     Parsed as RST -- the same way any other prose in this extension is --
     rather than treated as a special case: a hyperlink written as
@@ -781,7 +813,8 @@ def _build_segments(nodes_in_span: list[nodes.Node], ctx: _RenderContext) -> lis
             inner: list[Segment] = [('text', ['# SEE ALSO:'])]
             for later_node in nodes_in_span[i + 1 :]:
                 inner.extend(_convert_node(later_node, inner_ctx))
-            segments.append(('directive', _join_segments(inner)))
+            lines = _indent_label_content(_join_segments(inner), ctx.fmt)
+            segments.append(('directive', lines))
             break
         segments.extend(_convert_node(node, ctx))
     return segments
@@ -791,7 +824,7 @@ def _build_download_entries(
     app: Sphinx,
     docname: str,
     name: str,
-    header: Segment,
+    header_title: str,
     nodes_in_span: list[nodes.Node],
     formats: list[str],
     footer: str | None,
@@ -803,8 +836,10 @@ def _build_download_entries(
     requested -- empty if the span has no real code, or ``formats`` itself
     is empty. Shared by the docstring-Examples path and gallery-page path;
     the only differences between them are how ``nodes_in_span``/``name``
-    get built, and what ``header`` says (see ``_header_segment`` vs.
-    ``_process_gallery_page``'s own title handling).
+    get built, and what ``header_title`` says (see ``_header_title`` vs.
+    ``_process_gallery_page``'s own title handling). Always level 1 -- the
+    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')
     py_segments = _build_segments(nodes_in_span, py_ctx)
@@ -812,7 +847,8 @@ def _build_download_entries(
     if not any(kind == 'code' for kind, _lines in py_segments):
         return []
 
-    py_segments_full = [header, *py_segments, *_footer_segment(footer, 'py', app, docname)]
+    py_header = _title_underline_segment(header_title, 1, 'py')
+    py_segments_full = [py_header, *py_segments, *_footer_segment(footer, 'py', app, docname)]
     source = '\n'.join(_join_segments(py_segments_full)).rstrip() + '\n\n'
 
     if not _has_real_code(source):
@@ -828,6 +864,7 @@ def _build_download_entries(
         else:
             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
             # than joined into one segment list and converted together:
             # _segments_to_cells only starts a new cell when the kind
@@ -835,7 +872,7 @@ def _build_download_entries(
             # following non-code content (e.g. a trailing admonition) would
             # otherwise share its cell instead of always getting one of its
             # own.
-            cells = _segments_to_cells([header, *ipynb_segments])
+            cells = _segments_to_cells([ipynb_header, *ipynb_segments])
             cells.extend(_segments_to_cells(_footer_segment(footer, 'ipynb', app, docname)))
             rel_path = _write_notebook(app, name, _build_notebook(cells))
         entries.append((label, rel_path))
@@ -864,7 +901,7 @@ def _process_span(
 
     name = _qualified_name_for(heading, docname, counter)
     entries = _build_download_entries(
-        app, docname, name, _header_segment(name), nodes_in_span, formats, footer, link_labels
+        app, docname, name, _header_title(name), nodes_in_span, formats, footer, link_labels
     )
     if not entries:
         return
@@ -984,9 +1021,9 @@ def _process_gallery_page(
     # not an Examples section carved out of a larger docstring, so there's
     # no "from" framing to make. Falls back to the usual header on the off
     # chance the page has no title of its own.
-    header = _title_underline_segment(title) if title else _header_segment(name)
+    header_title = title if title else _header_title(name)
     entries = _build_download_entries(
-        app, docname, name, header, nodes_in_span, formats, footer, link_labels
+        app, docname, name, header_title, nodes_in_span, formats, footer, link_labels
     )
     if not entries:
         return

{sphinx_examples_as_code-0.3.1 → sphinx_examples_as_code-0.3.3}/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.3.1'
-__version_tuple__ = version_tuple = (0, 3, 1)
+__version__ = version = '0.3.3'
+__version_tuple__ = version_tuple = (0, 3, 3)
 
-__commit_id__ = commit_id = 'g6bae5922a'
+__commit_id__ = commit_id = 'g2a42d27a0'

{sphinx_examples_as_code-0.3.1 → sphinx_examples_as_code-0.3.3}/sphinx_examples_as_code.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.3.1
+Version: 0.3.3
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -107,9 +107,11 @@ What happens to the content of an Examples section:
 - `.. 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. "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.
+  comment followed by their content as comments, indented one level under the label in
+  `.py` (not `.ipynb`, where leading whitespace within a paragraph has no visible effect
+  once rendered). "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.
 - 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
@@ -154,14 +156,21 @@ Detection is automatic and per-page — any page without a sphinx-gallery downlo
 is left completely untouched. Gallery pages and ordinary docstring/prose pages (using
 the Examples-section behavior above) can coexist on the same site.
 
-A `# %%` cell with its own RST heading gets the same title-plus-underline treatment as
-the file's own header, and renders as a real Markdown heading in `.ipynb`. Level is
-relative to actual RST section nesting, not always one below the file's own header:
-level 1 (`<h1>`, `# Title` + `# ====`) for the file's own header, or a cell heading that
-reuses the page title's own underline character; level 2 (`<h2>`, `# Title` + `# ----`)
-for a cell heading nested under it (the common case), or one level below whatever
-heading precedes it. Level 3 and deeper use ATX syntax instead (`# ### Title`), since
-Markdown's underline-style headings only support two levels.
+A `# %%` cell with its own RST heading gets the same header treatment as the file's own
+title, and renders as a real Markdown heading in `.ipynb`. Level is relative to actual
+RST section nesting, not always one below the file's own header: a cell heading nested
+under the page's own title (the common case) is one level below it; one that reuses the
+page title's own underline character is level 1, the same as the file's own header; a
+cell heading nested under *that* is level 2 relative to it, and so on.
+
+Each format uses one heading style consistently across every level, rather than mixing
+styles:
+
+- `.py` uses an RST-style title + underline, one character per level -- the same
+  sequence Sphinx's own documentation uses for sections through sub-paragraphs: `=`, `-`,
+  `~`, `^`, `"`, `'` for levels 1 through 6.
+- `.ipynb` always uses ATX syntax (`#`, `##`, `###`, ...), since that's a real Markdown
+  heading at any level, whereas an underline only reads as one for the first two.
 
 Two things worth knowing before turning this on:
 

{sphinx_examples_as_code-0.3.1 → sphinx_examples_as_code-0.3.3}/sphinx_examples_as_code.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.3.1",
+  "tag": "0.3.3",
   "distance": 0,
-  "node": "g6bae5922a337380c3e8f439cfea8c645d1d11342",
+  "node": "g2a42d27a03ee769351e69a23c3392b167a7cbe45",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-07"

{sphinx_examples_as_code-0.3.1 → sphinx_examples_as_code-0.3.3}/tests/test_gallery_downloads.py

@@ -68,26 +68,29 @@ def _is_ours(path: Path) -> bool:
     """Distinguish our generated file from sphinx-gallery's own same-named one.
 
     Both write a ``plot_minimal.py``/``.ipynb`` under ``_downloads/<digest>/``
-    -- ours is identifiable structurally, by the title+underline header this
-    extension always starts a generated file with (its first two lines in
-    ``.py``, or its first markdown cell's first two lines in ``.ipynb``): a
-    title line followed by a line of ``=`` matching that title's length.
+    -- ours is identifiable structurally, by the level-1 header this
+    extension always starts a generated file with: a title line followed by
+    a line of ``=`` matching that title's length in ``.py``, or a single
+    ``# Title`` (ATX level 1) line as the first markdown cell's first line
+    in ``.ipynb`` (see ``_title_underline_segment``).
     """
     if path.suffix == '.py':
         lines = path.read_text(encoding='utf-8').splitlines()
-    else:
-        cells = json.loads(path.read_text(encoding='utf-8'))['cells']
-        # markdown lines carry a trailing hard-break "  " -- strip it before comparing
-        lines = (
-            [line.rstrip() for line in ''.join(cells[0]['source']).splitlines()] if cells else []
-        )
-
-    if len(lines) < 2:
+        if len(lines) < 2:
+            return False
+        title, underline = lines[0].removeprefix('# '), lines[1].removeprefix('# ')
+        return bool(title) and underline == '=' * len(title)
+
+    cells = json.loads(path.read_text(encoding='utf-8'))['cells']
+    if not cells or not cells[0]['source']:
         return False
-    title, underline = lines[0], lines[1]
-    if path.suffix == '.py':
-        title, underline = title.removeprefix('# '), underline.removeprefix('# ')
-    return bool(title) and underline == '=' * len(title)
+    # sphinx-gallery's own native notebook also titles its first cell
+    # "# <title>" (plain ATX, no hard break) -- ours is only distinguishable
+    # by the trailing two-space hard break _cell_source always adds
+    raw_first_line = cells[0]['source'][0]
+    first_line = raw_first_line.rstrip()
+    has_hard_break = raw_first_line.rstrip('\n').endswith('  ')
+    return has_hard_break and first_line.startswith('# ') and not first_line.startswith('# #')
 
 
 def test_gallery_downloads_disabled_by_default(tmp_path: Path):
@@ -221,7 +224,7 @@ def test_gallery_downloads_footer_is_its_own_dedicated_ipynb_cell(gallery_build:
 def test_gallery_downloads_sibling_section_heading_is_markdown_in_ipynb(
     gallery_build: tuple[Path, str],
 ):
-    """The sibling section's heading is a level-2 (``-`` underline) Markdown heading."""
+    """The sibling section's heading is a level-2 (``##``) Markdown heading."""
     html_dir, _html = gallery_build
     notebook = json.loads(_generated(html_dir, '.ipynb').read_text(encoding='utf-8'))
     heading_cell = next(
@@ -229,20 +232,20 @@ def test_gallery_downloads_sibling_section_heading_is_markdown_in_ipynb(
         for c in notebook['cells']
         if c['cell_type'] == 'markdown' and 'A headed cell' in ''.join(c['source'])
     )
-    source = ''.join(heading_cell['source'])
-    assert '-' * len('A headed cell') in source  # setext underline
+    lines = [line.rstrip() for line in heading_cell['source']]
+    assert '## A headed cell' in lines
 
 
 def test_gallery_downloads_page_title_is_level_1_sibling_heading_is_level_2(
     gallery_build: tuple[Path, str],
 ):
-    """The page's own title (``=``) outranks a sibling section's heading (``-``)."""
+    """The page's own title (``#``) outranks a sibling section's heading (``##``)."""
     html_dir, _html = gallery_build
     notebook = json.loads(_generated(html_dir, '.ipynb').read_text(encoding='utf-8'))
     title_cell = notebook['cells'][0]
-    title_source = ''.join(title_cell['source'])
-    assert '=' * len('A minimal gallery example') in title_source
-    assert '-' * len('A minimal gallery example') not in title_source
+    lines = [line.rstrip() for line in title_cell['source']]
+    assert '# A minimal gallery example' in lines
+    assert '## A minimal gallery example' not in lines
 
 
 def test_gallery_downloads_generated_py_executes(gallery_build: tuple[Path, str]):

{sphinx_examples_as_code-0.3.1 → sphinx_examples_as_code-0.3.3}/tests/test_heading_level_reuse.py

@@ -58,8 +58,16 @@ def test_reused_underline_char_renders_as_level_1(built: Path):
     assert lines[reused_idx + 1] == '# ' + '=' * len('Reused Top Level')
 
 
-def test_three_genuine_levels_uses_atx_for_the_third(built: Path):
-    """A subsection nested two sections deep gets ATX ``###``, not another dash line.
+def test_reused_underline_char_renders_as_level_1_in_ipynb(built: Path):
+    nb_path = _generated(built, 'plot_reused_level.ipynb')
+    notebook = json.loads(nb_path.read_text(encoding='utf-8'))
+    all_lines = [line.rstrip() for cell in notebook['cells'] for line in cell['source']]
+    assert '## Nested Subsection' in all_lines
+    assert '# Reused Top Level' in all_lines
+
+
+def test_three_genuine_levels_py_uses_tilde_for_the_third(built: Path):
+    """A subsection nested two sections deep gets a ``~`` underline, not another dash line.
 
     Otherwise it would render identically to its own parent section's
     heading -- indistinguishable from a sibling instead of a subsection.
@@ -70,11 +78,12 @@ def test_three_genuine_levels_uses_atx_for_the_third(built: Path):
     section_idx = lines.index('# Section')
     assert lines[section_idx + 1] == '# ' + '-' * len('Section')
 
-    assert '# ### Subsection' in lines
-    assert '# Subsection' not in lines  # not a level-2 dash heading
+    subsection_idx = lines.index('# Subsection')
+    assert lines[subsection_idx + 1] == '# ' + '~' * len('Subsection')
 
 
 def test_three_genuine_levels_atx_renders_as_h3_in_ipynb(built: Path):
+    """In .ipynb, every level uses ATX -- the third level is a plain ``###`` line."""
     nb_path = _generated(built, 'plot_three_levels.ipynb')
     notebook = json.loads(nb_path.read_text(encoding='utf-8'))
     all_source = ''.join(''.join(cell['source']) for cell in notebook['cells'])

{sphinx_examples_as_code-0.3.1 → sphinx_examples_as_code-0.3.3}/tests/test_sphinx_examples_as_code.py

@@ -444,6 +444,47 @@ def test_clean_code_comment_replaces_non_ascii_chars(unicode_char: int, ascii_ch
     assert seac._clean_code_comment(line) == f'# comment {ascii_char} text'
 
 
+# ---------------------------------------------------------------------------
+# _indent_comment_line / _indent_label_content
+# ---------------------------------------------------------------------------
+
+
+def test_indent_comment_line_indents_content():
+    assert seac._indent_comment_line('# hello') == '#     hello'
+
+
+def test_indent_comment_line_bare_hash_unchanged():
+    assert seac._indent_comment_line('#') == '#'
+
+
+def test_indent_comment_line_blank_separator_unchanged():
+    assert seac._indent_comment_line('') == ''
+
+
+def test_indent_comment_line_code_line_unchanged():
+    # no '#' prefix at all -- indenting it would change real Python source
+    assert seac._indent_comment_line('x = 1') == 'x = 1'
+
+
+def test_indent_label_content_py_indents_everything_after_the_first_line():
+    lines = ['# NOTE:', '# hello', '# world']
+    assert seac._indent_label_content(lines, 'py') == ['# NOTE:', '#     hello', '#     world']
+
+
+def test_indent_label_content_ipynb_unchanged():
+    lines = ['# NOTE:', '# hello', '# world']
+    assert seac._indent_label_content(lines, 'ipynb') == lines
+
+
+def test_indent_label_content_empty_list_unchanged():
+    assert seac._indent_label_content([], 'py') == []
+
+
+def test_indent_label_content_skips_only_the_first_line():
+    # a lone label with no content: nothing after it to indent
+    assert seac._indent_label_content(['# NOTE:'], 'py') == ['# NOTE:']
+
+
 # ---------------------------------------------------------------------------
 # _convert_admonition / _convert_node dispatch
 # ---------------------------------------------------------------------------
@@ -451,7 +492,19 @@ def test_clean_code_comment_replaces_non_ascii_chars(unicode_char: int, ascii_ch
 
 def test_convert_node_note():
     doctree = _parse('.. note::\n\n   hello')
-    assert seac._convert_node(doctree[0], _ctx()) == [('directive', ['# NOTE:', '# hello'])]
+    assert seac._convert_node(doctree[0], _ctx(fmt='py')) == [
+        ('directive', ['# NOTE:', '#     hello'])
+    ]
+
+
+def test_convert_node_note_ipynb_not_indented():
+    # unlike .py, .ipynb content isn't indented under the label -- once
+    # rendered as markdown, leading whitespace within a paragraph collapses
+    # to nothing anyway
+    doctree = _parse('.. note::\n\n   hello')
+    assert seac._convert_node(doctree[0], _ctx(fmt='ipynb')) == [
+        ('directive', ['# NOTE:', '# hello'])
+    ]
 
 
 def test_convert_node_seealso():
@@ -462,8 +515,8 @@ def test_convert_node_seealso():
     p2 += nodes.Text('More info')
     node += p1
     node += p2
-    assert seac._convert_node(node, _ctx()) == [
-        ('directive', ['# SEE ALSO:', '# See X', '# More info'])
+    assert seac._convert_node(node, _ctx(fmt='py')) == [
+        ('directive', ['# SEE ALSO:', '#     See X', '#     More info'])
     ]
 
 
@@ -478,7 +531,10 @@ def test_convert_node_seealso_propagates_in_see_also_to_references():
     ctx = _ctx(fmt='py', base_url='https://docs.pyvista.org/')
     segments = seac._convert_node(node, ctx)
     assert segments == [
-        ('directive', ['# SEE ALSO:', '# pyvista.Plotter https://docs.pyvista.org/plotter.html'])
+        (
+            'directive',
+            ['# SEE ALSO:', '#     pyvista.Plotter https://docs.pyvista.org/plotter.html'],
+        )
     ]
 
 
@@ -490,8 +546,8 @@ def test_convert_node_see_also_section_treated_like_admonition():
 
 def test_convert_node_generic_admonition_uses_title():
     doctree = _parse('.. admonition:: Custom Title\n\n   body text')
-    assert seac._convert_node(doctree[0], _ctx()) == [
-        ('directive', ['# Custom Title:', '# body text'])
+    assert seac._convert_node(doctree[0], _ctx(fmt='py')) == [
+        ('directive', ['# Custom Title:', '#     body text'])
     ]
 
 
@@ -500,7 +556,7 @@ def test_convert_node_generic_admonition_no_title_defaults_to_note():
     p = nodes.paragraph()
     p += nodes.Text('body')
     node += p
-    assert seac._convert_node(node, _ctx()) == [('directive', ['# NOTE:', '# body'])]
+    assert seac._convert_node(node, _ctx(fmt='py')) == [('directive', ['# NOTE:', '#     body'])]
 
 
 def test_convert_node_admonition_with_no_body_keeps_label():
@@ -508,6 +564,16 @@ def test_convert_node_admonition_with_no_body_keeps_label():
     assert seac._convert_node(node, _ctx()) == [('directive', ['# NOTE:'])]
 
 
+def test_convert_node_note_with_code_indents_text_not_code():
+    # a doctest example inside a note: the surrounding prose is indented
+    # under the label, but the code itself is left flush -- indenting it
+    # would be invalid Python (it isn't actually nested inside anything)
+    doctree = _parse('.. note::\n\n   See below.\n\n   >>> x = 1')
+    assert seac._convert_node(doctree[0], _ctx(fmt='py')) == [
+        ('directive', ['# NOTE:', '#     See below.', 'x = 1'])
+    ]
+
+
 def test_convert_node_skip_subtree_class():
     node = nodes.container(classes=['sd-dropdown'])
     p = nodes.paragraph()
@@ -747,38 +813,43 @@ def test_qualified_name_for_examples_section_sibling_no_desc_falls_back():
 # ---------------------------------------------------------------------------
 
 
-def test_header_segment_format():
-    kind, lines = seac._header_segment('pyvista.read')
-    assert kind == 'directive'
-    assert lines[0] == '# Examples from pyvista.read'
-    assert lines[1] == '# ' + '=' * len('Examples from pyvista.read')
+def test_header_title_format():
+    assert seac._header_title('pyvista.read') == 'Examples from pyvista.read'
 
 
 # ---------------------------------------------------------------------------
 # _title_underline_segment
 # ---------------------------------------------------------------------------
 
+# The full level -> underline character convention, for .py -- same
+# sequence Sphinx's own documentation uses for sections through
+# sub-paragraphs.
+_LEVEL_UNDERLINE_CHARS = {1: '=', 2: '-', 3: '~', 4: '^', 5: '"', 6: "'"}
+
 
-def test_title_underline_segment_format():
-    kind, lines = seac._title_underline_segment('A Title')
+@pytest.mark.parametrize('level', [1, 2, 3, 4, 5, 6])
+def test_title_underline_segment_py_uses_level_specific_underline(level):
+    kind, lines = seac._title_underline_segment('A Title', level, 'py')
     assert kind == 'directive'
-    assert lines == ['# A Title', '# =======']
+    char = _LEVEL_UNDERLINE_CHARS[level]
+    assert lines == ['# A Title', '# ' + char * len('A Title')]
 
 
-def test_title_underline_segment_level_2_uses_dashes():
-    kind, lines = seac._title_underline_segment('A Title', level=2)
+@pytest.mark.parametrize('level', [1, 2, 3, 4, 5, 6])
+def test_title_underline_segment_ipynb_always_uses_atx(level):
+    kind, lines = seac._title_underline_segment('A Title', level, 'ipynb')
     assert kind == 'directive'
-    assert lines == ['# A Title', '# -------']
+    assert lines == [f'# {"#" * level} A Title']
 
 
-def test_title_underline_segment_level_3_uses_atx():
-    kind, lines = seac._title_underline_segment('A Title', level=3)
+def test_title_underline_segment_py_level_beyond_6_clamped():
+    kind, lines = seac._title_underline_segment('A Title', 9, 'py')
     assert kind == 'directive'
-    assert lines == ['# ### A Title']
+    assert lines == ['# A Title', "# '''''''"]
 
 
-def test_title_underline_segment_level_6_uses_atx():
-    kind, lines = seac._title_underline_segment('A Title', level=6)
+def test_title_underline_segment_ipynb_level_beyond_6_clamped():
+    kind, lines = seac._title_underline_segment('A Title', 9, 'ipynb')
     assert kind == 'directive'
     assert lines == ['# ###### A Title']
 
@@ -841,39 +912,70 @@ def test_heading_level_reused_top_level_char_then_nested_subsection():
     assert seac._heading_level(title) == 2
 
 
-def test_convert_node_title_uses_underline_treatment():
+def _nest_title_one_deep(text: str) -> nodes.title:
     # nested one section inside a page's own title section -- the common
     # case for a gallery sibling section's heading
     page_section = nodes.section()
     section = nodes.section()
-    title = nodes.title('', 'A subsection')
+    title = nodes.title('', text)
     section += title
     page_section += section
-    assert seac._convert_node(title, _ctx()) == [
+    return title
+
+
+def test_convert_node_title_uses_underline_treatment():
+    title = _nest_title_one_deep('A subsection')
+    assert seac._convert_node(title, _ctx(fmt='py')) == [
         ('directive', ['# A subsection', '# ------------'])
     ]
 
 
+def test_convert_node_title_one_deep_ipynb_uses_atx():
+    title = _nest_title_one_deep('A subsection')
+    assert seac._convert_node(title, _ctx(fmt='ipynb')) == [('directive', ['# ## A subsection'])]
+
+
 def test_convert_node_title_not_nested_uses_level_1():
     section = nodes.section()
     title = nodes.title('', 'A subsection')
     section += title
-    assert seac._convert_node(title, _ctx()) == [
+    assert seac._convert_node(title, _ctx(fmt='py')) == [
         ('directive', ['# A subsection', '# ============'])
     ]
 
 
-def test_convert_node_title_two_sections_deep_uses_atx():
+def test_convert_node_title_not_nested_ipynb_uses_atx():
+    section = nodes.section()
+    title = nodes.title('', 'A subsection')
+    section += title
+    assert seac._convert_node(title, _ctx(fmt='ipynb')) == [('directive', ['# # A subsection'])]
+
+
+def _nest_title_three_deep(text: str) -> nodes.title:
     # e.g. a "# %%" cell's own heading nested inside another sibling
     # section's heading, rather than directly under the page's own title
     page_section = nodes.section()
     section = nodes.section()
     subsection = nodes.section()
-    title = nodes.title('', 'A sub-subsection')
+    title = nodes.title('', text)
     subsection += title
     section += subsection
     page_section += section
-    assert seac._convert_node(title, _ctx()) == [('directive', ['# ### A sub-subsection'])]
+    return title
+
+
+def test_convert_node_title_two_sections_deep_py_uses_tilde():
+    title = _nest_title_three_deep('A sub-subsection')
+    assert seac._convert_node(title, _ctx(fmt='py')) == [
+        ('directive', ['# A sub-subsection', '# ~~~~~~~~~~~~~~~~'])
+    ]
+
+
+def test_convert_node_title_two_sections_deep_ipynb_uses_atx():
+    title = _nest_title_three_deep('A sub-subsection')
+    assert seac._convert_node(title, _ctx(fmt='ipynb')) == [
+        ('directive', ['# ### A sub-subsection'])
+    ]
 
 
 def test_convert_node_empty_title_returns_empty():
@@ -1190,7 +1292,7 @@ def test_build_segments_bare_rubric_see_also_affects_only_what_follows():
             'directive',
             [
                 '# SEE ALSO:',
-                '# pyvista.Plotter https://docs.pyvista.org/plotter.html',
+                '#     pyvista.Plotter https://docs.pyvista.org/plotter.html',
                 'x = 1',
             ],
         )
@@ -1316,7 +1418,7 @@ def test_process_span_includes_external_see_also(tmp_path: Path):
     written = next((tmp_path / '_downloads').rglob('*.py'))
     content = written.read_text()
     assert '# SEE ALSO:' in content
-    assert '# related info' in content
+    assert '#     related info' in content
 
 
 def test_process_span_appends_footer_with_blank_line_before(tmp_path: Path):

{sphinx_examples_as_code-0.3.1 → sphinx_examples_as_code-0.3.3}/tests/test_tinypages.py

@@ -177,14 +177,14 @@ def test_docstring_examples_conversion(built: tuple[Path, list[Path]]):
 
     note_src = _read(examples, 'case_note')
     assert '# NOTE:' in note_src
-    assert '# This is a note' in note_src
+    assert '#     This is a note' in note_src  # indented under the label
 
     warning_src = _read(examples, 'case_warning')
     assert '# WARNING:' in warning_src
 
     multi_note_src = _read(examples, 'case_multi_paragraph_note')
-    assert '# First paragraph of the note.' in multi_note_src
-    assert '# Second paragraph of the note.' in multi_note_src
+    assert '#     First paragraph of the note.' in multi_note_src
+    assert '#     Second paragraph of the note.' in multi_note_src
 
     admonition_src = _read(examples, 'case_generic_admonition')
     assert '# Custom Title:' in admonition_src
@@ -249,6 +249,15 @@ def test_header_format(built: tuple[Path, list[Path]]):
     assert lines[2] == ''
 
 
+def test_header_format_ipynb_uses_atx(built_notebooks: list[Path]):
+    """The same header, in .ipynb, is a single ATX level-1 line -- no underline."""
+    nb_path = next(p for p in built_notebooks if p.stem == 'docstring_cases_case_note')
+    notebook = json.loads(nb_path.read_text(encoding='utf-8'))
+    header_cell = notebook['cells'][0]
+    lines = [line.rstrip() for line in header_cell['source']]
+    assert lines[0] == '# Examples from docstring_cases.case_note'
+
+
 def test_whitespace_conventions(built: tuple[Path, list[Path]]):
     """Check the spacing rules.
 
@@ -298,10 +307,10 @@ def test_seealso_admonition(built: tuple[Path, list[Path]]):
     """
     src = _read(built[1], 'case_seealso')
     assert '# SEE ALSO:' in src
-    assert '# Some Target' in src
-    assert '# See this in the gallery for more info.' in src
+    assert '#     Some Target' in src
+    assert '#     See this in the gallery for more info.' in src
     # each paragraph must be its own line -- not concatenated together
-    assert 'Some Target\n# See' in src or 'Some TargetSee' not in src
+    assert 'Some Target\n#     See' in src or 'Some TargetSee' not in src
 
 
 def test_stray_markup_in_doctest_comment_cleaned(built: tuple[Path, list[Path]]):
@@ -521,7 +530,7 @@ def test_base_url_set_resolves_links(tmp_path: Path):
     ):
         py_src = _read(py_files, name)
         assert '# SEE ALSO:' in py_src
-        assert '# docstring_cases.Sample https://docs.example.com/' in py_src
+        assert '#     docstring_cases.Sample https://docs.example.com/' in py_src
         assert '`docstring_cases.Sample`' not in py_src  # no backticks in See Also url lines
 
         nb_path = next(p for p in ipynb_files if p.stem == f'docstring_cases_{name}')
@@ -533,12 +542,19 @@ def test_markdown_cells_use_hard_line_breaks(built_notebooks: list[Path]):
     """Adjacent lines within one markdown cell need an explicit hard break.
 
     Without it, markdown treats a single newline as whitespace and runs
-    everything in the cell together into one paragraph.
+    everything in the cell together into one paragraph. Checked on the
+    note's own "# NOTE:" label line, immediately followed by its content
+    with no blank line between -- not the header cell, which is a single
+    ATX heading line with nothing else to connect to.
     """
     nb_path = next(p for p in built_notebooks if p.stem == 'docstring_cases_case_note')
     notebook = json.loads(nb_path.read_text(encoding='utf-8'))
-    header_cell = next(c for c in notebook['cells'] if c['cell_type'] == 'markdown')
-    assert header_cell['source'][0].endswith('  \n')
+    note_cell = next(
+        c
+        for c in notebook['cells']
+        if c['cell_type'] == 'markdown' and 'useful information' in ''.join(c['source'])
+    )
+    assert note_cell['source'][0].endswith('  \n')
 
 
 def test_html_baseurl_missing_scheme_disables_links_without_failing_build(tmp_path: Path):