sphinx-examples-as-code 0.6.1__tar.gz → 0.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. sphinx_examples_as_code-0.7.0/.github/dependabot.yml +22 -0
  2. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/.github/workflows/ci.yml +20 -4
  3. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/PKG-INFO +53 -29
  4. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/README.md +50 -28
  5. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/pyproject.toml +2 -0
  6. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/sphinx_examples_as_code/__init__.py +185 -51
  7. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/sphinx_examples_as_code/_version.py +3 -3
  8. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/sphinx_examples_as_code.egg-info/PKG-INFO +53 -29
  9. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/sphinx_examples_as_code.egg-info/requires.txt +3 -0
  10. sphinx_examples_as_code-0.7.0/sphinx_examples_as_code.egg-info/scm_version.json +8 -0
  11. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/test_gallery_downloads.py +84 -11
  12. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/test_heading_level_reuse.py +7 -7
  13. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/test_single_function_page.py +5 -5
  14. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/test_sphinx_examples_as_code.py +289 -127
  15. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/test_tinypages.py +79 -67
  16. sphinx_examples_as_code-0.6.1/.github/dependabot.yml +0 -16
  17. sphinx_examples_as_code-0.6.1/sphinx_examples_as_code.egg-info/scm_version.json +0 -8
  18. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/.github/release.yml +0 -0
  19. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/.gitignore +0 -0
  20. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/.pre-commit-config.yaml +0 -0
  21. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/LICENSE +0 -0
  22. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/setup.cfg +0 -0
  23. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/sphinx_examples_as_code.egg-info/SOURCES.txt +0 -0
  24. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/sphinx_examples_as_code.egg-info/dependency_links.txt +0 -0
  25. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/sphinx_examples_as_code.egg-info/scm_file_list.json +0 -0
  26. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/sphinx_examples_as_code.egg-info/top_level.txt +0 -0
  27. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/gallery_fixture/conf.py +0 -0
  28. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/gallery_fixture/examples/GALLERY_HEADER.rst +0 -0
  29. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/gallery_fixture/examples/plot_minimal.py +0 -0
  30. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/gallery_fixture/index.rst +0 -0
  31. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/heading_level_fixture/conf.py +0 -0
  32. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/heading_level_fixture/examples/GALLERY_HEADER.rst +0 -0
  33. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/heading_level_fixture/examples/plot_reused_level.py +0 -0
  34. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/heading_level_fixture/examples/plot_three_levels.py +0 -0
  35. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/heading_level_fixture/index.rst +0 -0
  36. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/single_function_fixture/conf.py +0 -0
  37. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/single_function_fixture/index.rst +0 -0
  38. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/single_function_fixture/mymodule.py +0 -0
  39. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/tinypages/conf.py +0 -0
  40. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/tinypages/docstring_cases.py +0 -0
  41. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/tinypages/docstring_cases.rst +0 -0
  42. {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/tinypages/index.rst +0 -0
@@ -0,0 +1,22 @@
1
+ version: 2
2
+ multi-ecosystem-groups:
3
+ maintenance:
4
+ schedule:
5
+ interval: quarterly
6
+ labels: [maintenance, dependencies]
7
+ updates:
8
+ - package-ecosystem: pip
9
+ directory: /
10
+ schedule:
11
+ interval: weekly
12
+ labels: [maintenance, dependencies]
13
+ allow:
14
+ - dependency-name: pyvista
15
+ - dependency-name: sphinx-gallery
16
+ groups:
17
+ project:
18
+ patterns: ['*']
19
+ - package-ecosystem: github-actions
20
+ directory: /
21
+ patterns: ['*']
22
+ multi-ecosystem-group: maintenance
@@ -22,7 +22,7 @@ jobs:
22
22
  with:
23
23
  persist-credentials: false
24
24
  fetch-depth: 0
25
- - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
25
+ - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
26
26
  with:
27
27
  enable-cache: false
28
28
  - run: uv sync --group dev --extra gallery
@@ -43,7 +43,7 @@ jobs:
43
43
  with:
44
44
  persist-credentials: false
45
45
  fetch-depth: 0
46
- - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
46
+ - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
47
47
  with:
48
48
  enable-cache: false
49
49
  - uses: pyvista/setup-headless-display-action@c103a2ff45650d38cb71684b5dc6cdfeb9442c79 # v5.1.0
@@ -51,7 +51,7 @@ jobs:
51
51
  pyvista: true
52
52
  - run: uv sync --group dev --extra gallery --python ${{ matrix.python-version }}
53
53
  - run: uv run pytest tests/ --cov --cov-report=xml
54
- - uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
54
+ - uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
55
55
  with:
56
56
  files: ./coverage.xml
57
57
  env:
@@ -65,7 +65,7 @@ jobs:
65
65
  with:
66
66
  persist-credentials: false
67
67
  fetch-depth: 0
68
- - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
68
+ - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
69
69
  with:
70
70
  enable-cache: false
71
71
  - run: uv build
@@ -87,3 +87,19 @@ jobs:
87
87
  name: dist
88
88
  path: dist/
89
89
  - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
90
+
91
+ release:
92
+ needs: publish
93
+ runs-on: ubuntu-latest
94
+ permissions:
95
+ contents: write
96
+ steps:
97
+ - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
98
+ with:
99
+ name: dist
100
+ path: dist/
101
+ # Notes come from the merged pull requests, shaped by .github/release.yml.
102
+ - env:
103
+ GH_TOKEN: ${{ github.token }}
104
+ TAG: ${{ github.ref_name }}
105
+ run: gh release create "$TAG" --repo "$GITHUB_REPOSITORY" --title "$TAG" --generate-notes --verify-tag dist/*
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: sphinx-examples-as-code
3
- Version: 0.6.1
3
+ Version: 0.7.0
4
4
  Summary: Sphinx extension for converting docstring examples into downloadable code.
5
5
  Author-email: The PyVista Developers <info@pyvista.org>
6
6
  License-Expression: MIT
@@ -25,12 +25,15 @@ License-File: LICENSE
25
25
  Requires-Dist: pyvista>=0.48
26
26
  Provides-Extra: gallery
27
27
  Requires-Dist: sphinx-gallery<0.23,>=0.22; extra == "gallery"
28
+ Provides-Extra: marimo
29
+ Requires-Dist: marimo>=0.14; extra == "marimo"
28
30
  Dynamic: license-file
29
31
 
30
32
  # sphinx-examples-as-code
31
33
 
32
34
  A Sphinx extension that turns docstring/page "Examples" sections into downloadable,
33
- runnable `.py` and/or `.ipynb` files, with a download link inserted into the section.
35
+ runnable Python scripts, Jupyter notebooks and/or [marimo](https://marimo.io) notebooks,
36
+ with a download link inserted into the section.
34
37
 
35
38
  Pages or docstrings without an Examples section are left completely untouched. Adding
36
39
  `sphinx_examples_as_code` to `conf.py`'s `extensions` is the only on/off switch.
@@ -48,6 +51,12 @@ Sphinx-Gallery integration is opt-in and needs a compatible sphinx-gallery, whic
48
51
  pip install 'sphinx-examples-as-code[gallery]'
49
52
  ```
50
53
 
54
+ marimo notebook downloads need marimo 0.14 or newer, which the `marimo` extra installs:
55
+
56
+ ```bash
57
+ pip install 'sphinx-examples-as-code[marimo]'
58
+ ```
59
+
51
60
  Add it to your Sphinx `conf.py`:
52
61
 
53
62
  ```python
@@ -65,23 +74,29 @@ the keys you want to change from their default:
65
74
  ```python
66
75
  sphinx_examples_as_code_conf = {
67
76
  'link_position': 'top',
68
- 'formats': ['py', 'ipynb'],
77
+ 'formats': ['python', 'jupyter', 'marimo'],
69
78
  'gallery_downloads': False,
70
79
  'footer': (
71
80
  'Generated by `sphinx-examples-as-code '
72
81
  '<https://github.com/pyvista/sphinx-examples-as-code>`_'
73
82
  ),
74
83
  'link_labels': {
75
- 'py': 'Download Python source code',
76
- 'ipynb': 'Download Jupyter notebook',
84
+ 'python': 'Download Python script',
85
+ 'jupyter': 'Download Jupyter notebook',
86
+ 'marimo': 'Download marimo notebook',
77
87
  },
78
88
  }
79
89
  ```
80
90
 
81
91
  - `link_position`: where the download link(s) land within the Examples section. `'top'`
82
92
  (default) or `'bottom'`.
83
- - `formats`: which downloads to generate. A list containing `'py'`, `'ipynb'`, or both
84
- (default). Always offered in that order regardless of how the list is written.
93
+ - `formats`: which downloads to generate. A list containing any of `'python'` (a plain
94
+ Python script, `<name>.py`), `'jupyter'` (a Jupyter notebook, `<name>.ipynb`) and
95
+ `'marimo'` (a marimo notebook, `<name>.marimo.py`); defaults to all three. Always
96
+ offered in that order regardless of how the list is written. Without marimo 0.14 or
97
+ newer installed, the default skips the marimo download, and a `formats` that names
98
+ `'marimo'` (in `conf.py` or through `-D`) stops the build with a configuration error. An unknown format raises a configuration error too;
99
+ the old `'py'` and `'ipynb'` names say what replaced them.
85
100
  - `link_labels`: the text of the download link(s) themselves, per format. Set only the
86
101
  format(s) you want to change; any left unset keep reading their own default shown above.
87
102
  - `gallery_downloads`: opt-in takeover of
@@ -91,11 +106,11 @@ sphinx_examples_as_code_conf = {
91
106
  - `footer`: a string appended to the end of every generated file. Defaults to a one-line
92
107
  "generated file" credit linking back to this project; set to `None` to omit it
93
108
  entirely. Preceded by a blank line and a `-`-only divider line, which also renders as a
94
- real horizontal rule in `.ipynb`; the footer always gets its own dedicated cell there.
109
+ real horizontal rule in notebooks; the footer always gets its own dedicated cell there.
95
110
  Parsed as RST: a hyperlink written as `` `text <url>`_ `` becomes a real clickable
96
- Markdown link in `.ipynb`, and renders inline as `text url` in `.py`. Plain text with no
97
- markup at all becomes one comment line per line of text, and blank-line-separated
98
- paragraphs stay separated.
111
+ Markdown link in notebooks, and renders inline as `text url` in Python scripts. Plain
112
+ text with no markup at all becomes one comment line per line of text, and
113
+ blank-line-separated paragraphs stay separated.
99
114
 
100
115
  An unrecognized key raises a configuration error at build start.
101
116
 
@@ -116,39 +131,43 @@ What happens to the content of an Examples section:
116
131
  - `.. code-block:: python` (or `py`) blocks are kept as-is; other languages become
117
132
  comments, set off with blank lines on both sides like any other directive.
118
133
  - Admonitions (`.. note::`, `.. warning::`, ...) become a `# LABEL:` comment followed by
119
- their content as comments, indented one level under the label in `.py` only.
134
+ their content as comments, indented one level under the label in Python scripts only.
120
135
  - A bullet/numbered list becomes a `-`/`N.`-marked line per item, set off with a blank
121
136
  line on both sides in either format — a bare `#` instead of a real blank line when
122
- that falls inside an admonition or a definition's own body in `.py`, so the whole
123
- thing still reads as one unbroken comment block. A definition list's term stays at
124
- the surrounding indent; its definition (the body nested under it) is indented one
125
- level further in `.py`, same as an admonition's own content.
137
+ that falls inside an admonition or a definition's own body in a Python script, so the
138
+ whole thing still reads as one unbroken comment block. A definition list's term stays
139
+ at the surrounding indent; its definition (the body nested under it) is indented one
140
+ level further in Python scripts, same as an admonition's own content.
126
141
  - Cross-references and inline code (`:class:`, `:meth:`, `:func:`, `:attr:`,
127
142
  double-backtick literals, ...) keep their display text, wrapped in backticks (e.g.
128
143
  ``:class:`pyvista.Plotter` `` -> `` `pyvista.Plotter` ``). If `html_baseurl` is set and
129
- the reference resolves, `.ipynb` turns it into a clickable link; `.py` never writes the
130
- link, only the display text.
144
+ the reference resolves, notebooks turn it into a clickable link; Python scripts never
145
+ write the link, only the display text.
131
146
  - Plain prose-style references (`:ref:`, `:doc:`) are treated the same way, minus the
132
147
  backticks.
133
148
  - Everything else text-bearing (prose, captions, other non-Python code) becomes a plain
134
149
  `#` comment.
135
150
  - A table becomes an aligned text table, its caption on the line above: an RST simple
136
- table in `.py`, a Markdown pipe table in `.ipynb`. Each cell is flattened to a single
137
- line, and a column left entirely empty -- one holding only images, say -- is dropped
138
- along with its heading.
151
+ table in Python scripts, a Markdown pipe table in notebooks. Each cell is flattened to a
152
+ single line, and a column left entirely empty -- one holding only images, say -- is
153
+ dropped along with its heading.
139
154
  - Figures/images, raw HTML, sphinx-design dropdowns/tab-sets, and sphinx-tags' `.. tags::`
140
155
  line are dropped entirely.
141
156
  - "See Also" content is always dropped.
142
157
 
143
- Generated `.py` files start with a `# Examples from <qualified name>` title header
158
+ Generated Python scripts start with a `# Examples from <qualified name>` title header
144
159
  (gallery mode uses the page's own title instead -- see below), with a few whitespace
145
160
  conventions: prose directly above a code block stays attached to it, a code block is
146
161
  always followed by a blank line, and a directive (header, `# NOTE:`-style block) gets
147
162
  blank lines on both sides.
148
163
 
149
- Generated `.ipynb` notebooks use the same content, split into alternating code/markdown
164
+ Generated Jupyter notebooks use the same content, split into alternating code/markdown
150
165
  cells instead.
151
166
 
167
+ Generated marimo notebooks are that same Jupyter notebook converted by marimo's own
168
+ converter, the one behind `marimo convert`. `from __future__` imports are dropped first,
169
+ so the notebook also runs as a plain script (`python <name>.marimo.py`).
170
+
152
171
  A download link is only added if the resulting code contains at least one real
153
172
  executable statement.
154
173
 
@@ -157,7 +176,7 @@ executable statement.
157
176
  With `sphinx_examples_as_code_conf['gallery_downloads'] = True`, this extension takes
158
177
  over the downloads on every page generated by
159
178
  [sphinx-gallery](https://sphinx-gallery.github.io): the "Go to the end to download the
160
- full example code" note and the `.py`/`.ipynb`/`.zip` download footer are removed from
179
+ full example code" note and the `.py`/`.zip` download footer are removed from
161
180
  the page, replaced with download link(s) built by this extension instead — same
162
181
  conversion rules as above, applied to the whole page rather than one Examples section.
163
182
  The generated file's header uses the page's own title (e.g. `# Create Circular Arcs`)
@@ -172,7 +191,7 @@ is left completely untouched. Gallery pages and ordinary docstring/prose pages (
172
191
  the Examples-section behavior above) can coexist on the same site.
173
192
 
174
193
  A `# %%` cell with its own RST heading gets the same header treatment as the file's own
175
- title, and renders as a real Markdown heading in `.ipynb`. Level is relative to actual
194
+ title, and renders as a real Markdown heading in notebooks. Level is relative to actual
176
195
  RST section nesting, not always one below the file's own header: a cell heading nested
177
196
  under the page's own title (the common case) is one level below it; one that reuses the
178
197
  page title's own underline character is level 1, the same as the file's own header; a
@@ -181,10 +200,10 @@ cell heading nested under *that* is level 2 relative to it, and so on.
181
200
  Each format uses one heading style consistently across every level, rather than mixing
182
201
  styles:
183
202
 
184
- - `.py` uses an RST-style title + underline, one character per level -- the same
203
+ - Python scripts use an RST-style title + underline, one character per level -- the same
185
204
  sequence Sphinx's own documentation uses for sections through sub-paragraphs: `=`, `-`,
186
205
  `~`, `^`, `"`, `'` for levels 1 through 6.
187
- - `.ipynb` always uses ATX syntax (`#`, `##`, `###`, ...) at every level.
206
+ - Notebooks always use ATX syntax (`#`, `##`, `###`, ...) at every level.
188
207
 
189
208
  Two things worth knowing before turning this on:
190
209
 
@@ -193,8 +212,13 @@ Two things worth knowing before turning this on:
193
212
  block — not a documented extension API. A future sphinx-gallery release could shift
194
213
  that structure without warning. Only sphinx-gallery 0.22.x is tested, so the `gallery`
195
214
  extra caps there rather than letting the next release quietly produce no downloads.
196
- - sphinx-gallery's own `.py`/`.ipynb`/`.zip` downloads still end up copied into
197
- `_downloads/`, even though nothing on the page links to them anymore.
215
+ - sphinx-gallery's own `.py`/`.zip` downloads still end up copied into `_downloads/`,
216
+ even though nothing on the page links to them anymore. Its `.ipynb` is never written:
217
+ with `gallery_downloads` on, this extension sets `sphinx_gallery_conf['pypandoc']` to
218
+ `False` and `sphinx_gallery_conf['notebook_extensions']` to an empty set before
219
+ sphinx-gallery reads them, so pandoc is not needed. Setting `pypandoc`,
220
+ `notebook_extensions`, `first_notebook_cell`, `last_notebook_cell` or `notebook_images`
221
+ yourself has no effect and is reported as a warning.
198
222
 
199
223
  ## Development
200
224
 
@@ -1,7 +1,8 @@
1
1
  # sphinx-examples-as-code
2
2
 
3
3
  A Sphinx extension that turns docstring/page "Examples" sections into downloadable,
4
- runnable `.py` and/or `.ipynb` files, with a download link inserted into the section.
4
+ runnable Python scripts, Jupyter notebooks and/or [marimo](https://marimo.io) notebooks,
5
+ with a download link inserted into the section.
5
6
 
6
7
  Pages or docstrings without an Examples section are left completely untouched. Adding
7
8
  `sphinx_examples_as_code` to `conf.py`'s `extensions` is the only on/off switch.
@@ -19,6 +20,12 @@ Sphinx-Gallery integration is opt-in and needs a compatible sphinx-gallery, whic
19
20
  pip install 'sphinx-examples-as-code[gallery]'
20
21
  ```
21
22
 
23
+ marimo notebook downloads need marimo 0.14 or newer, which the `marimo` extra installs:
24
+
25
+ ```bash
26
+ pip install 'sphinx-examples-as-code[marimo]'
27
+ ```
28
+
22
29
  Add it to your Sphinx `conf.py`:
23
30
 
24
31
  ```python
@@ -36,23 +43,29 @@ the keys you want to change from their default:
36
43
  ```python
37
44
  sphinx_examples_as_code_conf = {
38
45
  'link_position': 'top',
39
- 'formats': ['py', 'ipynb'],
46
+ 'formats': ['python', 'jupyter', 'marimo'],
40
47
  'gallery_downloads': False,
41
48
  'footer': (
42
49
  'Generated by `sphinx-examples-as-code '
43
50
  '<https://github.com/pyvista/sphinx-examples-as-code>`_'
44
51
  ),
45
52
  'link_labels': {
46
- 'py': 'Download Python source code',
47
- 'ipynb': 'Download Jupyter notebook',
53
+ 'python': 'Download Python script',
54
+ 'jupyter': 'Download Jupyter notebook',
55
+ 'marimo': 'Download marimo notebook',
48
56
  },
49
57
  }
50
58
  ```
51
59
 
52
60
  - `link_position`: where the download link(s) land within the Examples section. `'top'`
53
61
  (default) or `'bottom'`.
54
- - `formats`: which downloads to generate. A list containing `'py'`, `'ipynb'`, or both
55
- (default). Always offered in that order regardless of how the list is written.
62
+ - `formats`: which downloads to generate. A list containing any of `'python'` (a plain
63
+ Python script, `<name>.py`), `'jupyter'` (a Jupyter notebook, `<name>.ipynb`) and
64
+ `'marimo'` (a marimo notebook, `<name>.marimo.py`); defaults to all three. Always
65
+ offered in that order regardless of how the list is written. Without marimo 0.14 or
66
+ newer installed, the default skips the marimo download, and a `formats` that names
67
+ `'marimo'` (in `conf.py` or through `-D`) stops the build with a configuration error. An unknown format raises a configuration error too;
68
+ the old `'py'` and `'ipynb'` names say what replaced them.
56
69
  - `link_labels`: the text of the download link(s) themselves, per format. Set only the
57
70
  format(s) you want to change; any left unset keep reading their own default shown above.
58
71
  - `gallery_downloads`: opt-in takeover of
@@ -62,11 +75,11 @@ sphinx_examples_as_code_conf = {
62
75
  - `footer`: a string appended to the end of every generated file. Defaults to a one-line
63
76
  "generated file" credit linking back to this project; set to `None` to omit it
64
77
  entirely. Preceded by a blank line and a `-`-only divider line, which also renders as a
65
- real horizontal rule in `.ipynb`; the footer always gets its own dedicated cell there.
78
+ real horizontal rule in notebooks; the footer always gets its own dedicated cell there.
66
79
  Parsed as RST: a hyperlink written as `` `text <url>`_ `` becomes a real clickable
67
- Markdown link in `.ipynb`, and renders inline as `text url` in `.py`. Plain text with no
68
- markup at all becomes one comment line per line of text, and blank-line-separated
69
- paragraphs stay separated.
80
+ Markdown link in notebooks, and renders inline as `text url` in Python scripts. Plain
81
+ text with no markup at all becomes one comment line per line of text, and
82
+ blank-line-separated paragraphs stay separated.
70
83
 
71
84
  An unrecognized key raises a configuration error at build start.
72
85
 
@@ -87,39 +100,43 @@ What happens to the content of an Examples section:
87
100
  - `.. code-block:: python` (or `py`) blocks are kept as-is; other languages become
88
101
  comments, set off with blank lines on both sides like any other directive.
89
102
  - Admonitions (`.. note::`, `.. warning::`, ...) become a `# LABEL:` comment followed by
90
- their content as comments, indented one level under the label in `.py` only.
103
+ their content as comments, indented one level under the label in Python scripts only.
91
104
  - A bullet/numbered list becomes a `-`/`N.`-marked line per item, set off with a blank
92
105
  line on both sides in either format — a bare `#` instead of a real blank line when
93
- that falls inside an admonition or a definition's own body in `.py`, so the whole
94
- thing still reads as one unbroken comment block. A definition list's term stays at
95
- the surrounding indent; its definition (the body nested under it) is indented one
96
- level further in `.py`, same as an admonition's own content.
106
+ that falls inside an admonition or a definition's own body in a Python script, so the
107
+ whole thing still reads as one unbroken comment block. A definition list's term stays
108
+ at the surrounding indent; its definition (the body nested under it) is indented one
109
+ level further in Python scripts, same as an admonition's own content.
97
110
  - Cross-references and inline code (`:class:`, `:meth:`, `:func:`, `:attr:`,
98
111
  double-backtick literals, ...) keep their display text, wrapped in backticks (e.g.
99
112
  ``:class:`pyvista.Plotter` `` -> `` `pyvista.Plotter` ``). If `html_baseurl` is set and
100
- the reference resolves, `.ipynb` turns it into a clickable link; `.py` never writes the
101
- link, only the display text.
113
+ the reference resolves, notebooks turn it into a clickable link; Python scripts never
114
+ write the link, only the display text.
102
115
  - Plain prose-style references (`:ref:`, `:doc:`) are treated the same way, minus the
103
116
  backticks.
104
117
  - Everything else text-bearing (prose, captions, other non-Python code) becomes a plain
105
118
  `#` comment.
106
119
  - A table becomes an aligned text table, its caption on the line above: an RST simple
107
- table in `.py`, a Markdown pipe table in `.ipynb`. Each cell is flattened to a single
108
- line, and a column left entirely empty -- one holding only images, say -- is dropped
109
- along with its heading.
120
+ table in Python scripts, a Markdown pipe table in notebooks. Each cell is flattened to a
121
+ single line, and a column left entirely empty -- one holding only images, say -- is
122
+ dropped along with its heading.
110
123
  - Figures/images, raw HTML, sphinx-design dropdowns/tab-sets, and sphinx-tags' `.. tags::`
111
124
  line are dropped entirely.
112
125
  - "See Also" content is always dropped.
113
126
 
114
- Generated `.py` files start with a `# Examples from <qualified name>` title header
127
+ Generated Python scripts start with a `# Examples from <qualified name>` title header
115
128
  (gallery mode uses the page's own title instead -- see below), with a few whitespace
116
129
  conventions: prose directly above a code block stays attached to it, a code block is
117
130
  always followed by a blank line, and a directive (header, `# NOTE:`-style block) gets
118
131
  blank lines on both sides.
119
132
 
120
- Generated `.ipynb` notebooks use the same content, split into alternating code/markdown
133
+ Generated Jupyter notebooks use the same content, split into alternating code/markdown
121
134
  cells instead.
122
135
 
136
+ Generated marimo notebooks are that same Jupyter notebook converted by marimo's own
137
+ converter, the one behind `marimo convert`. `from __future__` imports are dropped first,
138
+ so the notebook also runs as a plain script (`python <name>.marimo.py`).
139
+
123
140
  A download link is only added if the resulting code contains at least one real
124
141
  executable statement.
125
142
 
@@ -128,7 +145,7 @@ executable statement.
128
145
  With `sphinx_examples_as_code_conf['gallery_downloads'] = True`, this extension takes
129
146
  over the downloads on every page generated by
130
147
  [sphinx-gallery](https://sphinx-gallery.github.io): the "Go to the end to download the
131
- full example code" note and the `.py`/`.ipynb`/`.zip` download footer are removed from
148
+ full example code" note and the `.py`/`.zip` download footer are removed from
132
149
  the page, replaced with download link(s) built by this extension instead — same
133
150
  conversion rules as above, applied to the whole page rather than one Examples section.
134
151
  The generated file's header uses the page's own title (e.g. `# Create Circular Arcs`)
@@ -143,7 +160,7 @@ is left completely untouched. Gallery pages and ordinary docstring/prose pages (
143
160
  the Examples-section behavior above) can coexist on the same site.
144
161
 
145
162
  A `# %%` cell with its own RST heading gets the same header treatment as the file's own
146
- title, and renders as a real Markdown heading in `.ipynb`. Level is relative to actual
163
+ title, and renders as a real Markdown heading in notebooks. Level is relative to actual
147
164
  RST section nesting, not always one below the file's own header: a cell heading nested
148
165
  under the page's own title (the common case) is one level below it; one that reuses the
149
166
  page title's own underline character is level 1, the same as the file's own header; a
@@ -152,10 +169,10 @@ cell heading nested under *that* is level 2 relative to it, and so on.
152
169
  Each format uses one heading style consistently across every level, rather than mixing
153
170
  styles:
154
171
 
155
- - `.py` uses an RST-style title + underline, one character per level -- the same
172
+ - Python scripts use an RST-style title + underline, one character per level -- the same
156
173
  sequence Sphinx's own documentation uses for sections through sub-paragraphs: `=`, `-`,
157
174
  `~`, `^`, `"`, `'` for levels 1 through 6.
158
- - `.ipynb` always uses ATX syntax (`#`, `##`, `###`, ...) at every level.
175
+ - Notebooks always use ATX syntax (`#`, `##`, `###`, ...) at every level.
159
176
 
160
177
  Two things worth knowing before turning this on:
161
178
 
@@ -164,8 +181,13 @@ Two things worth knowing before turning this on:
164
181
  block — not a documented extension API. A future sphinx-gallery release could shift
165
182
  that structure without warning. Only sphinx-gallery 0.22.x is tested, so the `gallery`
166
183
  extra caps there rather than letting the next release quietly produce no downloads.
167
- - sphinx-gallery's own `.py`/`.ipynb`/`.zip` downloads still end up copied into
168
- `_downloads/`, even though nothing on the page links to them anymore.
184
+ - sphinx-gallery's own `.py`/`.zip` downloads still end up copied into `_downloads/`,
185
+ even though nothing on the page links to them anymore. Its `.ipynb` is never written:
186
+ with `gallery_downloads` on, this extension sets `sphinx_gallery_conf['pypandoc']` to
187
+ `False` and `sphinx_gallery_conf['notebook_extensions']` to an empty set before
188
+ sphinx-gallery reads them, so pandoc is not needed. Setting `pypandoc`,
189
+ `notebook_extensions`, `first_notebook_cell`, `last_notebook_cell` or `notebook_images`
190
+ yourself has no effect and is reported as a warning.
169
191
 
170
192
  ## Development
171
193
 
@@ -4,6 +4,7 @@ requires = ['setuptools>=64', 'setuptools_scm>=8']
4
4
 
5
5
  [dependency-groups]
6
6
  dev = [
7
+ 'marimo>=0.14',
7
8
  'nbformat',
8
9
  'numpydoc',
9
10
  'pre-commit',
@@ -42,6 +43,7 @@ requires-python = '>=3.10'
42
43
 
43
44
  [project.optional-dependencies]
44
45
  gallery = ['sphinx-gallery>=0.22,<0.23']
46
+ marimo = ['marimo>=0.14']
45
47
 
46
48
  [project.urls]
47
49
  Homepage = 'https://github.com/pyvista/sphinx-examples-as-code'