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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.3.0
+Version: 0.3.1
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -155,11 +155,13 @@ is left completely untouched. Gallery pages and ordinary docstring/prose pages (
 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` (`<h1>` for the
-file's own header, `# Title` + `# ====`; `<h2>` for a cell heading, `# Title` + `# ----`).
-A cell heading nested under the page's own title (the common case) is level 2; one that
-reuses the page title's own underline character -- a real RST heading, one level up --
-is level 1, matching the file's own header.
+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.
 
 Two things worth knowing before turning this on:
 

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

@@ -128,11 +128,13 @@ is left completely untouched. Gallery pages and ordinary docstring/prose pages (
 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` (`<h1>` for the
-file's own header, `# Title` + `# ====`; `<h2>` for a cell heading, `# Title` + `# ----`).
-A cell heading nested under the page's own title (the common case) is level 2; one that
-reuses the page title's own underline character -- a real RST heading, one level up --
-is level 1, matching the file's own header.
+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.
 
 Two things worth knowing before turning this on:
 

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

@@ -368,23 +368,29 @@ def _convert_literal_block(node: nodes.literal_block) -> list[Segment]:
     return [('directive', comment_lines)]
 
 
-#: Setext underline character per heading level -- ``=`` for the file's own
-#: top-level header (level 1), ``-`` for a subheading (level 2). CommonMark's
-#: setext syntax only supports these two levels.
+#: 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: '-'}
 
 
 def _title_underline_segment(title: str, level: int = 1) -> Segment:
-    """Build a title + underline directive segment, e.g. ``# Title`` + ``# =====``.
-
-    Shared by the file's own header (see ``_header_segment``), which is
-    always level 1, and gallery mode's sibling-section headings, which are
-    level 2. The underline is what makes this render as a real Markdown
-    heading in ``.ipynb`` (setext-style, once the ``#`` comment prefix is
-    stripped for markdown cells) rather than plain text.
+    """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.
     """
-    underline = _TITLE_UNDERLINE_CHARS[level] * len(title)
-    return ('directive', [f'# {title}', f'# {underline}'])
+    if level <= 2:
+        underline = _TITLE_UNDERLINE_CHARS[level] * len(title)
+        return ('directive', [f'# {title}', f'# {underline}'])
+    return ('directive', [f'# {"#" * level} {title}'])
 
 
 def _heading_level(title: nodes.title) -> int:
@@ -392,16 +398,16 @@ 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, and so does anything nested
-    deeper (clamped -- the deepest level CommonMark's setext syntax can
-    represent).
+    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 = 0
     node: nodes.Node | None = title.parent
     while isinstance(node, nodes.section):
         level += 1
         node = node.parent
-    return min(level, 2)
+    return min(level, 6)
 
 
 def _convert_admonition(

{sphinx_examples_as_code-0.3.0 → sphinx_examples_as_code-0.3.1}/sphinx_examples_as_code/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.0'
-__version_tuple__ = version_tuple = (0, 3, 0)
+__version__ = version = '0.3.1'
+__version_tuple__ = version_tuple = (0, 3, 1)
 
-__commit_id__ = commit_id = 'g3c1ab701a'
+__commit_id__ = commit_id = 'g6bae5922a'

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.3.0
+Version: 0.3.1
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -155,11 +155,13 @@ is left completely untouched. Gallery pages and ordinary docstring/prose pages (
 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` (`<h1>` for the
-file's own header, `# Title` + `# ====`; `<h2>` for a cell heading, `# Title` + `# ----`).
-A cell heading nested under the page's own title (the common case) is level 2; one that
-reuses the page title's own underline character -- a real RST heading, one level up --
-is level 1, matching the file's own header.
+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.
 
 Two things worth knowing before turning this on:
 

{sphinx_examples_as_code-0.3.0 → sphinx_examples_as_code-0.3.1}/sphinx_examples_as_code.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ tests/heading_level_fixture/conf.py
 tests/heading_level_fixture/index.rst
 tests/heading_level_fixture/examples/GALLERY_HEADER.rst
 tests/heading_level_fixture/examples/plot_reused_level.py
+tests/heading_level_fixture/examples/plot_three_levels.py
 tests/single_function_fixture/conf.py
 tests/single_function_fixture/index.rst
 tests/single_function_fixture/mymodule.py

{sphinx_examples_as_code-0.3.0 → sphinx_examples_as_code-0.3.1}/sphinx_examples_as_code.egg-info/scm_file_list.json

@@ -1,33 +1,34 @@
 {
   "files": [
+    ".pre-commit-config.yaml",
+    "pyproject.toml",
     "LICENSE",
     "README.md",
-    ".pre-commit-config.yaml",
     ".gitignore",
-    "pyproject.toml",
     ".github/dependabot.yml",
     ".github/release.yml",
     ".github/workflows/ci.yml",
-    "sphinx_examples_as_code/__init__.py",
-    "tests/test_sphinx_examples_as_code.py",
-    "tests/test_single_function_page.py",
     "tests/test_tinypages.py",
-    "tests/test_gallery_downloads.py",
+    "tests/test_single_function_page.py",
     "tests/test_heading_level_reuse.py",
-    "tests/gallery_fixture/conf.py",
-    "tests/gallery_fixture/index.rst",
-    "tests/gallery_fixture/examples/GALLERY_HEADER.rst",
-    "tests/gallery_fixture/examples/plot_minimal.py",
-    "tests/heading_level_fixture/conf.py",
+    "tests/test_gallery_downloads.py",
+    "tests/test_sphinx_examples_as_code.py",
     "tests/heading_level_fixture/index.rst",
+    "tests/heading_level_fixture/conf.py",
     "tests/heading_level_fixture/examples/plot_reused_level.py",
+    "tests/heading_level_fixture/examples/plot_three_levels.py",
     "tests/heading_level_fixture/examples/GALLERY_HEADER.rst",
-    "tests/single_function_fixture/mymodule.py",
-    "tests/single_function_fixture/conf.py",
-    "tests/single_function_fixture/index.rst",
-    "tests/tinypages/docstring_cases.py",
+    "tests/tinypages/index.rst",
     "tests/tinypages/conf.py",
+    "tests/tinypages/docstring_cases.py",
     "tests/tinypages/docstring_cases.rst",
-    "tests/tinypages/index.rst"
+    "tests/gallery_fixture/index.rst",
+    "tests/gallery_fixture/conf.py",
+    "tests/gallery_fixture/examples/plot_minimal.py",
+    "tests/gallery_fixture/examples/GALLERY_HEADER.rst",
+    "tests/single_function_fixture/index.rst",
+    "tests/single_function_fixture/conf.py",
+    "tests/single_function_fixture/mymodule.py",
+    "sphinx_examples_as_code/__init__.py"
   ]
 }

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

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

sphinx_examples_as_code-0.3.1/tests/heading_level_fixture/examples/plot_three_levels.py

@@ -0,0 +1,19 @@
+"""Three level example
+===================
+
+Intro text.
+"""
+
+# %%
+# Section
+# -------
+
+from __future__ import annotations
+
+x = 1
+
+# %%
+# Subsection
+# """"""""""
+
+y = 2

sphinx_examples_as_code-0.3.1/tests/test_heading_level_reuse.py

@@ -0,0 +1,81 @@
+"""Real-build regression tests for gallery sibling-section heading levels.
+
+Builds a real sphinx-gallery site (not a hand-built doctree) covering:
+one sibling-section heading nested under the page's own title (the common
+case), one reusing the page title's own underline character (a real RST
+heading, one level up from the first), and three genuinely nested levels
+(page title, section, subsection). Complements the hand-built-doctree unit
+tests for ``_heading_level``/``_title_underline_segment`` in
+``test_sphinx_examples_as_code.py``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import shutil
+
+import pytest
+from test_gallery_downloads import _is_ours
+from test_tinypages import _run_sphinx_build
+from test_tinypages import _sphinx_build_cmd
+
+FIXTURE_DIR = Path(__file__).parent / 'heading_level_fixture'
+
+
+@pytest.fixture(scope='module')
+def built(tmp_path_factory) -> Path:
+    # Copy the fixture rather than building from it in place: sphinx-gallery
+    # writes its generated .rst files into the source tree itself as a side
+    # effect of building (see test_gallery_downloads.py's own _build()).
+    tmp_path = tmp_path_factory.mktemp('heading_level_build')
+    src_dir = tmp_path / 'src'
+    shutil.copytree(FIXTURE_DIR, src_dir)
+
+    html_dir = tmp_path / 'html'
+    doctree_dir = tmp_path / 'doctrees'
+    returncode, out, err = _run_sphinx_build(_sphinx_build_cmd(src_dir, html_dir, doctree_dir))
+    assert returncode == 0, f'sphinx build failed with stdout:\n{out}\nstderr:\n{err}\n'
+    return html_dir
+
+
+def _generated(html_dir: Path, name: str) -> Path:
+    # gallery_downloads=True leaves sphinx-gallery's own same-named download
+    # in place too (see test_gallery_downloads.py) -- _is_ours picks ours out.
+    matches = [p for p in (html_dir / '_downloads').rglob(name) if _is_ours(p)]
+    assert len(matches) == 1, f'expected exactly one generated {name}, got {matches}'
+    return matches[0]
+
+
+def test_reused_underline_char_renders_as_level_1(built: Path):
+    py_path = _generated(built, 'plot_reused_level.py')
+    lines = py_path.read_text(encoding='utf-8').splitlines()
+
+    nested_idx = lines.index('# Nested Subsection')
+    assert lines[nested_idx + 1] == '# ' + '-' * len('Nested Subsection')
+
+    reused_idx = lines.index('# Reused Top Level')
+    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.
+
+    Otherwise it would render identically to its own parent section's
+    heading -- indistinguishable from a sibling instead of a subsection.
+    """
+    py_path = _generated(built, 'plot_three_levels.py')
+    lines = py_path.read_text(encoding='utf-8').splitlines()
+
+    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
+
+
+def test_three_genuine_levels_atx_renders_as_h3_in_ipynb(built: Path):
+    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'])
+    assert '### Subsection' in all_source

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

@@ -771,6 +771,18 @@ def test_title_underline_segment_level_2_uses_dashes():
     assert lines == ['# A Title', '# -------']
 
 
+def test_title_underline_segment_level_3_uses_atx():
+    kind, lines = seac._title_underline_segment('A Title', level=3)
+    assert kind == 'directive'
+    assert lines == ['# ### A Title']
+
+
+def test_title_underline_segment_level_6_uses_atx():
+    kind, lines = seac._title_underline_segment('A Title', level=6)
+    assert kind == 'directive'
+    assert lines == ['# ###### A Title']
+
+
 # ---------------------------------------------------------------------------
 # _heading_level
 # ---------------------------------------------------------------------------
@@ -785,7 +797,7 @@ def test_heading_level_one_section_deep_is_level_2():
     assert seac._heading_level(title) == 2
 
 
-def test_heading_level_two_sections_deep_is_clamped_to_2():
+def test_heading_level_two_sections_deep_is_3():
     page_section = nodes.section()
     section = nodes.section()
     subsection = nodes.section()
@@ -793,7 +805,18 @@ def test_heading_level_two_sections_deep_is_clamped_to_2():
     subsection += title
     section += subsection
     page_section += section
-    assert seac._heading_level(title) == 2
+    assert seac._heading_level(title) == 3
+
+
+def test_heading_level_clamped_to_6():
+    current = nodes.section()
+    for _ in range(8):
+        nested = nodes.section()
+        current += nested
+        current = nested
+    title = nodes.title('', 'Very deeply nested')
+    current += title
+    assert seac._heading_level(title) == 6
 
 
 def test_heading_level_not_nested_under_anything_is_level_1():
@@ -840,6 +863,19 @@ def test_convert_node_title_not_nested_uses_level_1():
     ]
 
 
+def test_convert_node_title_two_sections_deep_uses_atx():
+    # 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')
+    subsection += title
+    section += subsection
+    page_section += section
+    assert seac._convert_node(title, _ctx()) == [('directive', ['# ### A sub-subsection'])]
+
+
 def test_convert_node_empty_title_returns_empty():
     assert seac._convert_node(nodes.title(), _ctx()) == []
 

sphinx_examples_as_code-0.3.0/tests/test_heading_level_reuse.py

@@ -1,41 +0,0 @@
-"""Real-build regression test for gallery sibling-section heading levels.
-
-Builds a real sphinx-gallery site (not a hand-built doctree) with two
-sibling-section headings: one nested under the page's own title (the
-common case), one reusing the page title's own underline character (a
-real RST heading, one level up from the first). Complements the
-hand-built-doctree unit tests for ``_heading_level`` in
-``test_sphinx_examples_as_code.py``.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-import shutil
-
-from test_tinypages import _run_sphinx_build
-from test_tinypages import _sphinx_build_cmd
-
-FIXTURE_DIR = Path(__file__).parent / 'heading_level_fixture'
-
-
-def test_reused_underline_char_renders_as_level_1(tmp_path: Path):
-    # Copy the fixture rather than building from it in place: sphinx-gallery
-    # writes its generated .rst files into the source tree itself as a side
-    # effect of building (see test_gallery_downloads.py's own _build()).
-    src_dir = tmp_path / 'src'
-    shutil.copytree(FIXTURE_DIR, src_dir)
-
-    html_dir = tmp_path / 'html'
-    doctree_dir = tmp_path / 'doctrees'
-    returncode, out, err = _run_sphinx_build(_sphinx_build_cmd(src_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('plot_reused_level.py'))
-    lines = py_path.read_text(encoding='utf-8').splitlines()
-
-    nested_idx = lines.index('# Nested Subsection')
-    assert lines[nested_idx + 1] == '# ' + '-' * len('Nested Subsection')
-
-    reused_idx = lines.index('# Reused Top Level')
-    assert lines[reused_idx + 1] == '# ' + '=' * len('Reused Top Level')