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

{sphinx_examples_as_code-0.3.2 → 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.2
+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

{sphinx_examples_as_code-0.3.2 → 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

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

@@ -411,6 +411,36 @@ def _heading_level(title: nodes.title) -> int:
     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(
     node: nodes.Element, label: str, ctx: _RenderContext, *, skip_first_title: bool = False
 ) -> list[Segment]:
@@ -421,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]:
@@ -782,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

{sphinx_examples_as_code-0.3.2 → 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.2'
-__version_tuple__ = version_tuple = (0, 3, 2)
+__version__ = version = '0.3.3'
+__version_tuple__ = version_tuple = (0, 3, 3)
 
-__commit_id__ = commit_id = 'gf152e27a3'
+__commit_id__ = commit_id = 'g2a42d27a0'

{sphinx_examples_as_code-0.3.2 → 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.2
+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

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

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

{sphinx_examples_as_code-0.3.2 → 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()
@@ -1226,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',
             ],
         )
@@ -1352,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.2 → 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
@@ -307,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]]):
@@ -530,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}')