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.
- sphinx_examples_as_code-0.7.0/.github/dependabot.yml +22 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/.github/workflows/ci.yml +20 -4
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/PKG-INFO +53 -29
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/README.md +50 -28
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/pyproject.toml +2 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/sphinx_examples_as_code/__init__.py +185 -51
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/sphinx_examples_as_code/_version.py +3 -3
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/sphinx_examples_as_code.egg-info/PKG-INFO +53 -29
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/sphinx_examples_as_code.egg-info/requires.txt +3 -0
- sphinx_examples_as_code-0.7.0/sphinx_examples_as_code.egg-info/scm_version.json +8 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/test_gallery_downloads.py +84 -11
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/test_heading_level_reuse.py +7 -7
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/test_single_function_page.py +5 -5
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/test_sphinx_examples_as_code.py +289 -127
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/test_tinypages.py +79 -67
- sphinx_examples_as_code-0.6.1/.github/dependabot.yml +0 -16
- sphinx_examples_as_code-0.6.1/sphinx_examples_as_code.egg-info/scm_version.json +0 -8
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/.github/release.yml +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/.gitignore +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/.pre-commit-config.yaml +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/LICENSE +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/setup.cfg +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/sphinx_examples_as_code.egg-info/SOURCES.txt +0 -0
- {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
- {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
- {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
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/gallery_fixture/conf.py +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/gallery_fixture/examples/GALLERY_HEADER.rst +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/gallery_fixture/examples/plot_minimal.py +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/gallery_fixture/index.rst +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/heading_level_fixture/conf.py +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/heading_level_fixture/examples/GALLERY_HEADER.rst +0 -0
- {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
- {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
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/heading_level_fixture/index.rst +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/single_function_fixture/conf.py +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/single_function_fixture/index.rst +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/single_function_fixture/mymodule.py +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/tinypages/conf.py +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/tinypages/docstring_cases.py +0 -0
- {sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.7.0}/tests/tinypages/docstring_cases.rst +0 -0
- {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@
|
|
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@
|
|
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@
|
|
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@
|
|
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.
|
|
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
|
|
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': ['
|
|
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
|
-
'
|
|
76
|
-
'
|
|
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 `'
|
|
84
|
-
|
|
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
|
|
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
|
|
97
|
-
markup at all becomes one comment line per line of text, and
|
|
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
|
|
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
|
|
123
|
-
thing still reads as one unbroken comment block. A definition list's term stays
|
|
124
|
-
the surrounding indent; its definition (the body nested under it) is indented one
|
|
125
|
-
level further in
|
|
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,
|
|
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
|
|
137
|
-
line, and a column left entirely empty -- one holding only images, say -- is
|
|
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
|
|
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
|
|
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`/`.
|
|
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
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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`/`.
|
|
197
|
-
|
|
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
|
|
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': ['
|
|
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
|
-
'
|
|
47
|
-
'
|
|
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 `'
|
|
55
|
-
|
|
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
|
|
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
|
|
68
|
-
markup at all becomes one comment line per line of text, and
|
|
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
|
|
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
|
|
94
|
-
thing still reads as one unbroken comment block. A definition list's term stays
|
|
95
|
-
the surrounding indent; its definition (the body nested under it) is indented one
|
|
96
|
-
level further in
|
|
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,
|
|
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
|
|
108
|
-
line, and a column left entirely empty -- one holding only images, say -- is
|
|
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
|
|
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
|
|
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`/`.
|
|
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
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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`/`.
|
|
168
|
-
|
|
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'
|