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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.4.0
+Version: 0.4.1
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -120,9 +120,11 @@ What happens to the content of an Examples section:
   `.. rubric:: See Also`, or a hand-written `See Also` heading) and always renders the
   same way.
 - A bullet/numbered list becomes a `-`/`N.`-marked line per item, set off with a blank
-  line on both sides in either format. A definition list's term stays at the surrounding
-  indent; its definition (the body nested under it) is indented one level further in
-  `.py`, same as an admonition's own content.
+  line on both sides in either format — a bare `#` instead of a real blank line when
+  that falls inside an admonition or a definition's own body in `.py`, so the whole
+  thing still reads as one unbroken comment block. A definition list's term stays at
+  the surrounding indent; its definition (the body nested under it) is indented one
+  level further in `.py`, same as an admonition's own content.
 - Cross-references and inline code (`:class:`, `:meth:`, `:func:`, `:attr:`,
   double-backtick literals, ...) keep their display text, wrapped in backticks (e.g.
   ``:class:`pyvista.Plotter` `` -> `` `pyvista.Plotter` ``). If `html_baseurl` is set and

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

@@ -93,9 +93,11 @@ What happens to the content of an Examples section:
   `.. rubric:: See Also`, or a hand-written `See Also` heading) and always renders the
   same way.
 - A bullet/numbered list becomes a `-`/`N.`-marked line per item, set off with a blank
-  line on both sides in either format. A definition list's term stays at the surrounding
-  indent; its definition (the body nested under it) is indented one level further in
-  `.py`, same as an admonition's own content.
+  line on both sides in either format — a bare `#` instead of a real blank line when
+  that falls inside an admonition or a definition's own body in `.py`, so the whole
+  thing still reads as one unbroken comment block. A definition list's term stays at
+  the surrounding indent; its definition (the body nested under it) is indented one
+  level further in `.py`, same as an admonition's own content.
 - Cross-references and inline code (`:class:`, `:meth:`, `:func:`, `:attr:`,
   double-backtick literals, ...) keep their display text, wrapped in backticks (e.g.
   ``:class:`pyvista.Plotter` `` -> `` `pyvista.Plotter` ``). If `html_baseurl` is set and

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

@@ -403,6 +403,34 @@ def _indent_comment_line(line: str) -> str:
     return f'# {_ADMONITION_CONTENT_INDENT}{line.removeprefix("# ")}'
 
 
+def _is_raw_code_line(line: str) -> bool:
+    """Check whether a rendered ``.py`` line is real code, not a ``#`` comment line."""
+    return bool(line) and not line.startswith('#')
+
+
+def _fill_comment_gaps(lines: list[str]) -> list[str]:
+    """Turn a blank separator line into a bare ``#`` unless it borders raw code.
+
+    ``_join_segments`` forces a blank line around some segment boundaries
+    (e.g. a paragraph followed by a nested list) meant to visually separate
+    unrelated top-level content. Folded into one ``# LABEL:`` comment block
+    instead (see ``_indent_label_content``/``_definition_segment``), that
+    same blank line needs a ``#`` to still read as part of that one block.
+    A blank line bordering a raw code line (left flush and uncommented --
+    see ``_convert_node``'s doctest/literal-block handling) stays blank,
+    since that boundary really is between code and comment.
+    """
+    result: list[str] = []
+    for i, line in enumerate(lines):
+        if line != '':
+            result.append(line)
+            continue
+        before = lines[i - 1] if i > 0 else ''
+        after = lines[i + 1] if i + 1 < len(lines) else ''
+        result.append(line if _is_raw_code_line(before) or _is_raw_code_line(after) else '#')
+    return result
+
+
 def _indent_label_content(lines: list[str], fmt: str) -> list[str]:
     """Indent every line after the first (a ``# LABEL:`` line) under it.
 
@@ -410,7 +438,8 @@ def _indent_label_content(lines: list[str], fmt: str) -> list[str]:
     """
     if fmt != 'py' or not lines:
         return lines
-    return [lines[0], *(_indent_comment_line(line) for line in lines[1:])]
+    label, *rest = _fill_comment_gaps(lines)
+    return [label, *(_indent_comment_line(line) for line in rest)]
 
 
 def _definition_segment(node: nodes.definition, ctx: _RenderContext) -> list[Segment]:
@@ -423,7 +452,7 @@ def _definition_segment(node: nodes.definition, ctx: _RenderContext) -> list[Seg
         segments.extend(_convert_node(child, ctx))
     lines = _join_segments(segments)
     if ctx.fmt == 'py':
-        lines = [_indent_comment_line(line) for line in lines]
+        lines = [_indent_comment_line(line) for line in _fill_comment_gaps(lines)]
     return [('text', lines)] if lines else []
 
 

{sphinx_examples_as_code-0.4.0 → sphinx_examples_as_code-0.4.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.4.0'
-__version_tuple__ = version_tuple = (0, 4, 0)
+__version__ = version = '0.4.1'
+__version_tuple__ = version_tuple = (0, 4, 1)
 
-__commit_id__ = commit_id = 'ge8e70c9b9'
+__commit_id__ = commit_id = 'gfbf3dad3c'

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.4.0
+Version: 0.4.1
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -120,9 +120,11 @@ What happens to the content of an Examples section:
   `.. rubric:: See Also`, or a hand-written `See Also` heading) and always renders the
   same way.
 - A bullet/numbered list becomes a `-`/`N.`-marked line per item, set off with a blank
-  line on both sides in either format. A definition list's term stays at the surrounding
-  indent; its definition (the body nested under it) is indented one level further in
-  `.py`, same as an admonition's own content.
+  line on both sides in either format — a bare `#` instead of a real blank line when
+  that falls inside an admonition or a definition's own body in `.py`, so the whole
+  thing still reads as one unbroken comment block. A definition list's term stays at
+  the surrounding indent; its definition (the body nested under it) is indented one
+  level further in `.py`, same as an admonition's own content.
 - Cross-references and inline code (`:class:`, `:meth:`, `:func:`, `:attr:`,
   double-backtick literals, ...) keep their display text, wrapped in backticks (e.g.
   ``:class:`pyvista.Plotter` `` -> `` `pyvista.Plotter` ``). If `html_baseurl` is set and

{sphinx_examples_as_code-0.4.0 → sphinx_examples_as_code-0.4.1}/sphinx_examples_as_code.egg-info/scm_version.json

@@ -1,7 +1,7 @@
 {
-  "tag": "0.4.0",
+  "tag": "0.4.1",
   "distance": 0,
-  "node": "ge8e70c9b93c8984fd11c6144985637d91f8c59f3",
+  "node": "gfbf3dad3c895f46b35267a9ce9bc87e21d891625",
   "dirty": false,
   "branch": "HEAD",
   "node_date": "2026-08-11"

{sphinx_examples_as_code-0.4.0 → sphinx_examples_as_code-0.4.1}/tests/test_sphinx_examples_as_code.py

@@ -491,6 +491,68 @@ def test_indent_label_content_skips_only_the_first_line():
     assert seac._indent_label_content(['# NOTE:'], 'py') == ['# NOTE:']
 
 
+def test_indent_label_content_fills_gap_between_two_comment_lines():
+    # a forced blank between a paragraph and a following list (see
+    # _join_segments) must not read as the comment block ending partway
+    # through
+    lines = ['# SEE ALSO:', '# intro', '', '# - item one']
+    assert seac._indent_label_content(lines, 'py') == [
+        '# SEE ALSO:',
+        '#     intro',
+        '#',
+        '#     - item one',
+    ]
+
+
+def test_indent_label_content_keeps_real_blank_next_to_code():
+    # a blank line bordering raw, uncommented code (see
+    # test_convert_node_note_with_code_indents_text_not_code) stays a real
+    # blank line -- turning it into '#' would misrepresent it as a comment
+    lines = ['# NOTE:', '# intro', '', 'x = 1']
+    assert seac._indent_label_content(lines, 'py') == ['# NOTE:', '#     intro', '', 'x = 1']
+
+
+# ---------------------------------------------------------------------------
+# _fill_comment_gaps
+# ---------------------------------------------------------------------------
+
+
+def test_fill_comment_gaps_between_comments_becomes_hash():
+    assert seac._fill_comment_gaps(['# a', '', '# b']) == ['# a', '#', '# b']
+
+
+def test_fill_comment_gaps_next_to_code_stays_blank():
+    assert seac._fill_comment_gaps(['# a', '', 'x = 1']) == ['# a', '', 'x = 1']
+    assert seac._fill_comment_gaps(['x = 1', '', '# a']) == ['x = 1', '', '# a']
+
+
+def test_fill_comment_gaps_leading_and_trailing_blank():
+    assert seac._fill_comment_gaps(['', '# a']) == ['#', '# a']
+    assert seac._fill_comment_gaps(['# a', '']) == ['# a', '#']
+
+
+def test_fill_comment_gaps_no_blanks_unchanged():
+    lines = ['# a', '# b']
+    assert seac._fill_comment_gaps(lines) == lines
+
+
+# ---------------------------------------------------------------------------
+# _is_raw_code_line
+# ---------------------------------------------------------------------------
+
+
+def test_is_raw_code_line_true_for_code():
+    assert seac._is_raw_code_line('x = 1')
+
+
+def test_is_raw_code_line_false_for_comment():
+    assert not seac._is_raw_code_line('# x = 1')
+
+
+def test_is_raw_code_line_false_for_blank():
+    assert not seac._is_raw_code_line('')
+
+
 # ---------------------------------------------------------------------------
 # _definition_segment
 # ---------------------------------------------------------------------------
@@ -526,6 +588,23 @@ def test_definition_segment_empty_returns_empty():
     assert seac._convert_node(nodes.definition(), _ctx()) == []
 
 
+def test_definition_segment_py_fills_gap_before_nested_list():
+    # a paragraph followed by a nested bullet list inside one definition --
+    # the forced blank line between them (see _join_segments) must not
+    # break the definition out of its own '#'-commented block
+    definition = nodes.definition()
+    definition += nodes.paragraph('', 'intro text')
+    bullet_list = nodes.bullet_list()
+    item = nodes.list_item()
+    item += nodes.paragraph('', 'first item')
+    bullet_list += item
+    definition += bullet_list
+
+    assert seac._convert_node(definition, _ctx(fmt='py')) == [
+        ('text', ['#     intro text', '#', '#     - first item'])
+    ]
+
+
 def test_convert_node_definition_list_item_term_not_indented_definition_is():
     # the term itself stays at the surrounding indent level -- only its
     # definition (the body nested under it) gets the extra indent

{sphinx_examples_as_code-0.4.0 → sphinx_examples_as_code-0.4.1}/tests/test_tinypages.py

@@ -330,9 +330,10 @@ def test_seealso_structured_py(built: tuple[Path, list[Path]]):
     assert lines[term_idx + 1] == '#         See this dataset in the gallery for more info.'
 
     intro_idx = lines.index('#     This dataset is used in the following examples:')
-    # the bullet list is set off with a blank line before it, each item
-    # '- '-marked, back at the base (non-definition) indent level
-    assert lines[intro_idx + 1] == ''
+    # the bullet list is set off with a bare '#' before it (not a real blank
+    # line -- the whole SEE ALSO body stays one unbroken comment block),
+    # each item '- '-marked, back at the base (non-definition) indent level
+    assert lines[intro_idx + 1] == '#'
     assert lines[intro_idx + 2] == '#     - Some Target'
     assert lines[intro_idx + 3] == '#     - Some Target'