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

sphinx_examples_as_code-0.8.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+multi-ecosystem-groups:
+  maintenance:
+    schedule:
+      interval: quarterly
+    labels: [maintenance, dependencies]
+updates:
+- package-ecosystem: pip
+  directory: /
+  schedule:
+    interval: weekly
+  labels: [maintenance, dependencies]
+  allow:
+  - dependency-name: pyvista
+  - dependency-name: sphinx-gallery
+  groups:
+    project:
+      patterns: ['*']
+- package-ecosystem: github-actions
+  directory: /
+  patterns: ['*']
+  multi-ecosystem-group: maintenance

{sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.8.0}/.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
       with:
         persist-credentials: false
         fetch-depth: 0
-    - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4   # v10.1.0
+    - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7   # v10.2.0
       with:
         enable-cache: false
     - run: uv sync --group dev --extra gallery
@@ -43,7 +43,7 @@ jobs:
       with:
         persist-credentials: false
         fetch-depth: 0
-    - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4   # v10.1.0
+    - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7   # v10.2.0
       with:
         enable-cache: false
     - uses: pyvista/setup-headless-display-action@c103a2ff45650d38cb71684b5dc6cdfeb9442c79   # v5.1.0
@@ -51,7 +51,7 @@ jobs:
         pyvista: true
     - run: uv sync --group dev --extra gallery --python ${{ matrix.python-version }}
     - run: uv run pytest tests/ --cov --cov-report=xml
-    - uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f   # v7.0.0
+    - uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5   # v7.1.1
       with:
         files: ./coverage.xml
       env:
@@ -65,7 +65,7 @@ jobs:
       with:
         persist-credentials: false
         fetch-depth: 0
-    - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4   # v10.1.0
+    - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7   # v10.2.0
       with:
         enable-cache: false
     - run: uv build
@@ -87,3 +87,19 @@ jobs:
         name: dist
         path: dist/
     - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33   # release/v1
+
+  release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c   # v8.0.1
+      with:
+        name: dist
+        path: dist/
+      # Notes come from the merged pull requests, shaped by .github/release.yml.
+    - env:
+        GH_TOKEN: ${{ github.token }}
+        TAG: ${{ github.ref_name }}
+      run: gh release create "$TAG" --repo "$GITHUB_REPOSITORY" --title "$TAG" --generate-notes --verify-tag dist/*

{sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.6.1
+Version: 0.8.0
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -22,15 +22,19 @@ Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: packaging>=22
 Requires-Dist: pyvista>=0.48
 Provides-Extra: gallery
 Requires-Dist: sphinx-gallery<0.23,>=0.22; extra == "gallery"
+Provides-Extra: marimo
+Requires-Dist: marimo>=0.14; extra == "marimo"
 Dynamic: license-file
 
 # sphinx-examples-as-code
 
 A Sphinx extension that turns docstring/page "Examples" sections into downloadable,
-runnable `.py` and/or `.ipynb` files, with a download link inserted into the section.
+runnable Python scripts, Jupyter notebooks and/or [marimo](https://marimo.io) notebooks,
+with a download link inserted into the section.
 
 Pages or docstrings without an Examples section are left completely untouched. Adding
 `sphinx_examples_as_code` to `conf.py`'s `extensions` is the only on/off switch.
@@ -48,6 +52,12 @@ Sphinx-Gallery integration is opt-in and needs a compatible sphinx-gallery, whic
 pip install 'sphinx-examples-as-code[gallery]'
 ```
 
+marimo notebook downloads need marimo 0.14 or newer, which the `marimo` extra installs:
+
+```bash
+pip install 'sphinx-examples-as-code[marimo]'
+```
+
 Add it to your Sphinx `conf.py`:
 
 ```python
@@ -65,23 +75,32 @@ the keys you want to change from their default:
 ```python
 sphinx_examples_as_code_conf = {
     'link_position': 'top',
-    'formats': ['py', 'ipynb'],
+    'formats': ['python', 'jupyter', 'marimo'],
     'gallery_downloads': False,
     'footer': (
         'Generated by `sphinx-examples-as-code '
         '<https://github.com/pyvista/sphinx-examples-as-code>`_'
     ),
     'link_labels': {
-        'py': 'Download Python source code',
-        'ipynb': 'Download Jupyter notebook',
+        'python': 'Download Python script',
+        'jupyter': 'Download Jupyter notebook',
+        'marimo': 'Download marimo notebook',
     },
+    'script_metadata': False,
+    'dependencies': {},
+    'requires_python': None,
 }
 ```
 
 - `link_position`: where the download link(s) land within the Examples section. `'top'`
   (default) or `'bottom'`.
-- `formats`: which downloads to generate. A list containing `'py'`, `'ipynb'`, or both
-  (default). Always offered in that order regardless of how the list is written.
+- `formats`: which downloads to generate. A list containing any of `'python'` (a plain
+  Python script, `<name>.py`), `'jupyter'` (a Jupyter notebook, `<name>.ipynb`) and
+  `'marimo'` (a marimo notebook, `<name>.marimo.py`); defaults to all three. Always
+  offered in that order regardless of how the list is written. Without marimo 0.14 or
+  newer installed, the default skips the marimo download, and a `formats` that names
+  `'marimo'` (in `conf.py` or through `-D`) stops the build with a configuration error. An unknown format raises a configuration error too;
+  the old `'py'` and `'ipynb'` names say what replaced them.
 - `link_labels`: the text of the download link(s) themselves, per format. Set only the
   format(s) you want to change; any left unset keep reading their own default shown above.
 - `gallery_downloads`: opt-in takeover of
@@ -91,11 +110,22 @@ sphinx_examples_as_code_conf = {
 - `footer`: a string appended to the end of every generated file. Defaults to a one-line
   "generated file" credit linking back to this project; set to `None` to omit it
   entirely. Preceded by a blank line and a `-`-only divider line, which also renders as a
-  real horizontal rule in `.ipynb`; the footer always gets its own dedicated cell there.
+  real horizontal rule in notebooks; the footer always gets its own dedicated cell there.
   Parsed as RST: a hyperlink written as `` `text <url>`_ `` becomes a real clickable
-  Markdown link in `.ipynb`, and renders inline as `text url` in `.py`. Plain text with no
-  markup at all becomes one comment line per line of text, and blank-line-separated
-  paragraphs stay separated.
+  Markdown link in notebooks, and renders inline as `text url` in Python scripts. Plain
+  text with no markup at all becomes one comment line per line of text, and
+  blank-line-separated paragraphs stay separated.
+- `script_metadata`: `True` adds each download's dependencies and a one-line run
+  command. See [Dependencies and run commands](#dependencies-and-run-commands) below.
+  `False` (default) adds neither.
+- `dependencies`: extra PEP 508 requirements per format, added to the detected ones, e.g.
+  `{'jupyter': ['pyvista[jupyter]']}`. An entry naming a detected project replaces it,
+  so `{'python': ['pyvista>=0.46']}` sets its version. An entry without a version keeps
+  the automatic pin described below. Only used with `script_metadata` on.
+- `requires_python`: a `requires-python` specifier for the dependency block, e.g.
+  `'>=3.10'`. `None` (default) derives one from the dependencies instead; see
+  [Dependencies and run commands](#dependencies-and-run-commands). Only used with
+  `script_metadata` on.
 
 An unrecognized key raises a configuration error at build start.
 
@@ -107,6 +137,46 @@ Overriding a single key from the command line works via a dotted `-D` flag, e.g.
 `-D sphinx_examples_as_code_conf.link_position=bottom` -- this only touches that one
 key, leaving the rest (`conf.py`'s values, or the defaults) alone.
 
+## Dependencies and run commands
+
+With `script_metadata` on, each download lists the third-party projects its code
+imports, plus any `dependencies` set for its format, and says how to run it:
+
+- Python scripts start with a [PEP 723](https://peps.python.org/pep-0723/) `# /// script`
+  block, followed by `# Run this script with: uv run <name>.py`.
+- Jupyter notebooks say `` Open this notebook with: `uvx --python "<requires-python>" --from jupyterlab --with <dependency> ... jupyter-lab <name>.ipynb` `` in their first cell,
+  with `--python` only when there is a `requires-python`. Arguments are double-quoted where
+  needed, so the command works in bash, zsh, PowerShell and cmd. An argument containing
+  `"`, `$`, a backtick, `\`, `%` or a `!` not followed by `=` is single-quoted instead,
+  which cmd does not understand.
+- marimo notebooks start with the same `# /// script` block, which also lists `marimo`,
+  followed by `# Open this notebook with: uvx marimo edit --sandbox <name>.marimo.py`.
+- Each run command is followed by a line linking to
+  [uv's installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+
+Imports are read from the code, not run. Each imported top-level module maps to the
+project that provides it in the environment building the docs; standard-library
+modules, relative imports and modules no single installed project provides are left
+out. Projects the code needs but never imports, such as an optional backend, go in
+`dependencies`.
+
+The project named by Sphinx's own `project` setting (e.g. `project = 'PyVista'`) gets
+extra treatment when an example imports it and it is installed: its dependency becomes
+`<name>>=X.Y`, the installed release's major and minor version, or plain `<name>` for a
+pre-release or dev build.
+
+Unless `requires_python` is set, the block's `requires-python` combines:
+
+- that project's own `Requires-Python`, e.g. `>=3.10`, when it is listed;
+- `<3.N`, one minor version above the newest Python named in the `Programming Language ::
+  Python :: 3.X` classifiers of that project and of every listed dependency installed
+  from a platform-specific wheel, as installed in the environment building the docs.
+  Pure-Python dependencies and dependencies without such classifiers don't count, and
+  the bound is dropped when it would exclude every Python the project's own
+  `Requires-Python` allows.
+
+With neither, the line is left out.
+
 ## Conversion rules
 
 What happens to the content of an Examples section:
@@ -116,39 +186,43 @@ 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::`, ...) become a `# LABEL:` comment followed by
-  their content as comments, indented one level under the label in `.py` only.
+  their content as comments, indented one level under the label in Python scripts only.
 - A bullet/numbered list becomes a `-`/`N.`-marked line per item, set off with a blank
   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.
+  that falls inside an admonition or a definition's own body in a Python script, 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 Python scripts, 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
-  the reference resolves, `.ipynb` turns it into a clickable link; `.py` never writes the
-  link, only the display text.
+  the reference resolves, notebooks turn it into a clickable link; Python scripts never
+  write the link, only the display text.
 - Plain prose-style references (`:ref:`, `:doc:`) are treated the same way, minus the
   backticks.
 - Everything else text-bearing (prose, captions, other non-Python code) becomes a plain
   `#` comment.
 - A table becomes an aligned text table, its caption on the line above: an RST simple
-  table in `.py`, a Markdown pipe table in `.ipynb`. Each cell is flattened to a single
-  line, and a column left entirely empty -- one holding only images, say -- is dropped
-  along with its heading.
+  table in Python scripts, a Markdown pipe table in notebooks. Each cell is flattened to a
+  single line, and a column left entirely empty -- one holding only images, say -- is
+  dropped along with its heading.
 - Figures/images, raw HTML, sphinx-design dropdowns/tab-sets, and sphinx-tags' `.. tags::`
   line are dropped entirely.
 - "See Also" content is always dropped.
 
-Generated `.py` files start with a `# Examples from <qualified name>` title header
+Generated Python scripts start with a `# Examples from <qualified name>` title header
 (gallery mode uses the page's own title instead -- see below), with a few whitespace
 conventions: prose directly above a code block stays attached to it, a code block is
 always followed by a blank line, and a directive (header, `# NOTE:`-style block) gets
 blank lines on both sides.
 
-Generated `.ipynb` notebooks use the same content, split into alternating code/markdown
+Generated Jupyter notebooks use the same content, split into alternating code/markdown
 cells instead.
 
+Generated marimo notebooks are that same Jupyter notebook converted by marimo's own
+converter, the one behind `marimo convert`. `from __future__` imports are dropped first,
+so the notebook also runs as a plain script (`python <name>.marimo.py`).
+
 A download link is only added if the resulting code contains at least one real
 executable statement.
 
@@ -157,7 +231,7 @@ executable statement.
 With `sphinx_examples_as_code_conf['gallery_downloads'] = True`, this extension takes
 over the downloads on every page generated by
 [sphinx-gallery](https://sphinx-gallery.github.io): the "Go to the end to download the
-full example code" note and the `.py`/`.ipynb`/`.zip` download footer are removed from
+full example code" note and the `.py`/`.zip` download footer are removed from
 the page, replaced with download link(s) built by this extension instead — same
 conversion rules as above, applied to the whole page rather than one Examples section.
 The generated file's header uses the page's own title (e.g. `# Create Circular Arcs`)
@@ -172,7 +246,7 @@ 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 header treatment as the file's own
-title, and renders as a real Markdown heading in `.ipynb`. Level is relative to actual
+title, and renders as a real Markdown heading in notebooks. Level is relative to actual
 RST section nesting, not always one below the file's own header: a cell heading nested
 under the page's own title (the common case) is one level below it; one that reuses the
 page title's own underline character is level 1, the same as the file's own header; a
@@ -181,10 +255,10 @@ cell heading nested under *that* is level 2 relative to it, and so on.
 Each format uses one heading style consistently across every level, rather than mixing
 styles:
 
-- `.py` uses an RST-style title + underline, one character per level -- the same
+- Python scripts use an RST-style title + underline, one character per level -- the same
   sequence Sphinx's own documentation uses for sections through sub-paragraphs: `=`, `-`,
   `~`, `^`, `"`, `'` for levels 1 through 6.
-- `.ipynb` always uses ATX syntax (`#`, `##`, `###`, ...) at every level.
+- Notebooks always use ATX syntax (`#`, `##`, `###`, ...) at every level.
 
 Two things worth knowing before turning this on:
 
@@ -193,8 +267,13 @@ Two things worth knowing before turning this on:
   block — not a documented extension API. A future sphinx-gallery release could shift
   that structure without warning. Only sphinx-gallery 0.22.x is tested, so the `gallery`
   extra caps there rather than letting the next release quietly produce no downloads.
-- sphinx-gallery's own `.py`/`.ipynb`/`.zip` downloads still end up copied into
-  `_downloads/`, even though nothing on the page links to them anymore.
+- sphinx-gallery's own `.py`/`.zip` downloads still end up copied into `_downloads/`,
+  even though nothing on the page links to them anymore. Its `.ipynb` is never written:
+  with `gallery_downloads` on, this extension sets `sphinx_gallery_conf['pypandoc']` to
+  `False` and `sphinx_gallery_conf['notebook_extensions']` to an empty set before
+  sphinx-gallery reads them, so pandoc is not needed. Setting `pypandoc`,
+  `notebook_extensions`, `first_notebook_cell`, `last_notebook_cell` or `notebook_images`
+  yourself has no effect and is reported as a warning.
 
 ## Development
 

sphinx_examples_as_code-0.8.0/README.md

@@ -0,0 +1,252 @@
+# sphinx-examples-as-code
+
+A Sphinx extension that turns docstring/page "Examples" sections into downloadable,
+runnable Python scripts, Jupyter notebooks and/or [marimo](https://marimo.io) notebooks,
+with a download link inserted into the section.
+
+Pages or docstrings without an Examples section are left completely untouched. Adding
+`sphinx_examples_as_code` to `conf.py`'s `extensions` is the only on/off switch.
+
+## Installation
+
+```bash
+pip install sphinx-examples-as-code
+```
+
+Sphinx-Gallery integration is opt-in and needs a compatible sphinx-gallery, which the
+`gallery` extra pins:
+
+```bash
+pip install 'sphinx-examples-as-code[gallery]'
+```
+
+marimo notebook downloads need marimo 0.14 or newer, which the `marimo` extra installs:
+
+```bash
+pip install 'sphinx-examples-as-code[marimo]'
+```
+
+Add it to your Sphinx `conf.py`:
+
+```python
+extensions = [
+    ...,
+    'sphinx_examples_as_code',
+]
+```
+
+## Configuration
+
+Everything lives in one dict in `conf.py`, `sphinx_examples_as_code_conf` -- set only
+the keys you want to change from their default:
+
+```python
+sphinx_examples_as_code_conf = {
+    'link_position': 'top',
+    'formats': ['python', 'jupyter', 'marimo'],
+    'gallery_downloads': False,
+    'footer': (
+        'Generated by `sphinx-examples-as-code '
+        '<https://github.com/pyvista/sphinx-examples-as-code>`_'
+    ),
+    'link_labels': {
+        'python': 'Download Python script',
+        'jupyter': 'Download Jupyter notebook',
+        'marimo': 'Download marimo notebook',
+    },
+    'script_metadata': False,
+    'dependencies': {},
+    'requires_python': None,
+}
+```
+
+- `link_position`: where the download link(s) land within the Examples section. `'top'`
+  (default) or `'bottom'`.
+- `formats`: which downloads to generate. A list containing any of `'python'` (a plain
+  Python script, `<name>.py`), `'jupyter'` (a Jupyter notebook, `<name>.ipynb`) and
+  `'marimo'` (a marimo notebook, `<name>.marimo.py`); defaults to all three. Always
+  offered in that order regardless of how the list is written. Without marimo 0.14 or
+  newer installed, the default skips the marimo download, and a `formats` that names
+  `'marimo'` (in `conf.py` or through `-D`) stops the build with a configuration error. An unknown format raises a configuration error too;
+  the old `'py'` and `'ipynb'` names say what replaced them.
+- `link_labels`: the text of the download link(s) themselves, per format. Set only the
+  format(s) you want to change; any left unset keep reading their own default shown above.
+- `gallery_downloads`: opt-in takeover of
+  [sphinx-gallery](https://sphinx-gallery.github.io)'s own per-example downloads.
+  `False` (default) leaves sphinx-gallery pages untouched. See
+  [Sphinx-Gallery integration](#sphinx-gallery-integration) below.
+- `footer`: a string appended to the end of every generated file. Defaults to a one-line
+  "generated file" credit linking back to this project; set to `None` to omit it
+  entirely. Preceded by a blank line and a `-`-only divider line, which also renders as a
+  real horizontal rule in notebooks; the footer always gets its own dedicated cell there.
+  Parsed as RST: a hyperlink written as `` `text <url>`_ `` becomes a real clickable
+  Markdown link in notebooks, and renders inline as `text url` in Python scripts. Plain
+  text with no markup at all becomes one comment line per line of text, and
+  blank-line-separated paragraphs stay separated.
+- `script_metadata`: `True` adds each download's dependencies and a one-line run
+  command. See [Dependencies and run commands](#dependencies-and-run-commands) below.
+  `False` (default) adds neither.
+- `dependencies`: extra PEP 508 requirements per format, added to the detected ones, e.g.
+  `{'jupyter': ['pyvista[jupyter]']}`. An entry naming a detected project replaces it,
+  so `{'python': ['pyvista>=0.46']}` sets its version. An entry without a version keeps
+  the automatic pin described below. Only used with `script_metadata` on.
+- `requires_python`: a `requires-python` specifier for the dependency block, e.g.
+  `'>=3.10'`. `None` (default) derives one from the dependencies instead; see
+  [Dependencies and run commands](#dependencies-and-run-commands). Only used with
+  `script_metadata` on.
+
+An unrecognized key raises a configuration error at build start.
+
+Cross-references and hyperlinks resolve into absolute links using Sphinx's own
+[`html_baseurl`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl).
+Leave it unset and no links are generated anywhere.
+
+Overriding a single key from the command line works via a dotted `-D` flag, e.g.
+`-D sphinx_examples_as_code_conf.link_position=bottom` -- this only touches that one
+key, leaving the rest (`conf.py`'s values, or the defaults) alone.
+
+## Dependencies and run commands
+
+With `script_metadata` on, each download lists the third-party projects its code
+imports, plus any `dependencies` set for its format, and says how to run it:
+
+- Python scripts start with a [PEP 723](https://peps.python.org/pep-0723/) `# /// script`
+  block, followed by `# Run this script with: uv run <name>.py`.
+- Jupyter notebooks say `` Open this notebook with: `uvx --python "<requires-python>" --from jupyterlab --with <dependency> ... jupyter-lab <name>.ipynb` `` in their first cell,
+  with `--python` only when there is a `requires-python`. Arguments are double-quoted where
+  needed, so the command works in bash, zsh, PowerShell and cmd. An argument containing
+  `"`, `$`, a backtick, `\`, `%` or a `!` not followed by `=` is single-quoted instead,
+  which cmd does not understand.
+- marimo notebooks start with the same `# /// script` block, which also lists `marimo`,
+  followed by `# Open this notebook with: uvx marimo edit --sandbox <name>.marimo.py`.
+- Each run command is followed by a line linking to
+  [uv's installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+
+Imports are read from the code, not run. Each imported top-level module maps to the
+project that provides it in the environment building the docs; standard-library
+modules, relative imports and modules no single installed project provides are left
+out. Projects the code needs but never imports, such as an optional backend, go in
+`dependencies`.
+
+The project named by Sphinx's own `project` setting (e.g. `project = 'PyVista'`) gets
+extra treatment when an example imports it and it is installed: its dependency becomes
+`<name>>=X.Y`, the installed release's major and minor version, or plain `<name>` for a
+pre-release or dev build.
+
+Unless `requires_python` is set, the block's `requires-python` combines:
+
+- that project's own `Requires-Python`, e.g. `>=3.10`, when it is listed;
+- `<3.N`, one minor version above the newest Python named in the `Programming Language ::
+  Python :: 3.X` classifiers of that project and of every listed dependency installed
+  from a platform-specific wheel, as installed in the environment building the docs.
+  Pure-Python dependencies and dependencies without such classifiers don't count, and
+  the bound is dropped when it would exclude every Python the project's own
+  `Requires-Python` allows.
+
+With neither, the line is left out.
+
+## Conversion rules
+
+What happens to the content of an Examples section:
+
+- Doctest blocks (`>>> ...` / `... ...`) keep their input lines, prompts stripped, as
+  real Python source. Doctest *output* lines are dropped — only the input code matters.
+- `.. 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::`, ...) become a `# LABEL:` comment followed by
+  their content as comments, indented one level under the label in Python scripts only.
+- A bullet/numbered list becomes a `-`/`N.`-marked line per item, set off with a blank
+  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 a Python script, 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 Python scripts, 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
+  the reference resolves, notebooks turn it into a clickable link; Python scripts never
+  write the link, only the display text.
+- Plain prose-style references (`:ref:`, `:doc:`) are treated the same way, minus the
+  backticks.
+- Everything else text-bearing (prose, captions, other non-Python code) becomes a plain
+  `#` comment.
+- A table becomes an aligned text table, its caption on the line above: an RST simple
+  table in Python scripts, a Markdown pipe table in notebooks. Each cell is flattened to a
+  single line, and a column left entirely empty -- one holding only images, say -- is
+  dropped along with its heading.
+- Figures/images, raw HTML, sphinx-design dropdowns/tab-sets, and sphinx-tags' `.. tags::`
+  line are dropped entirely.
+- "See Also" content is always dropped.
+
+Generated Python scripts start with a `# Examples from <qualified name>` title header
+(gallery mode uses the page's own title instead -- see below), with a few whitespace
+conventions: prose directly above a code block stays attached to it, a code block is
+always followed by a blank line, and a directive (header, `# NOTE:`-style block) gets
+blank lines on both sides.
+
+Generated Jupyter notebooks use the same content, split into alternating code/markdown
+cells instead.
+
+Generated marimo notebooks are that same Jupyter notebook converted by marimo's own
+converter, the one behind `marimo convert`. `from __future__` imports are dropped first,
+so the notebook also runs as a plain script (`python <name>.marimo.py`).
+
+A download link is only added if the resulting code contains at least one real
+executable statement.
+
+## Sphinx-Gallery integration
+
+With `sphinx_examples_as_code_conf['gallery_downloads'] = True`, this extension takes
+over the downloads on every page generated by
+[sphinx-gallery](https://sphinx-gallery.github.io): the "Go to the end to download the
+full example code" note and the `.py`/`.zip` download footer are removed from
+the page, replaced with download link(s) built by this extension instead — same
+conversion rules as above, applied to the whole page rather than one Examples section.
+The generated file's header uses the page's own title (e.g. `# Create Circular Arcs`)
+rather than the generic `# Examples from <docname>`.
+
+The "Total running time" line and the "Gallery generated by Sphinx-Gallery" credit line
+stay on the rendered page untouched, but never make it into the generated download
+itself.
+
+Detection is automatic and per-page — any page without a sphinx-gallery download footer
+is left completely untouched. Gallery pages and ordinary docstring/prose pages (using
+the Examples-section behavior above) can coexist on the same site.
+
+A `# %%` cell with its own RST heading gets the same header treatment as the file's own
+title, and renders as a real Markdown heading in notebooks. Level is relative to actual
+RST section nesting, not always one below the file's own header: a cell heading nested
+under the page's own title (the common case) is one level below it; one that reuses the
+page title's own underline character is level 1, the same as the file's own header; a
+cell heading nested under *that* is level 2 relative to it, and so on.
+
+Each format uses one heading style consistently across every level, rather than mixing
+styles:
+
+- Python scripts use an RST-style title + underline, one character per level -- the same
+  sequence Sphinx's own documentation uses for sections through sub-paragraphs: `=`, `-`,
+  `~`, `^`, `"`, `'` for levels 1 through 6.
+- Notebooks always use ATX syntax (`#`, `##`, `###`, ...) at every level.
+
+Two things worth knowing before turning this on:
+
+- It's built against sphinx-gallery's own doctree output — the `sphx-glr-*` CSS classes
+  its own theming depends on, and the private node type holding a highlighted code
+  block — not a documented extension API. A future sphinx-gallery release could shift
+  that structure without warning. Only sphinx-gallery 0.22.x is tested, so the `gallery`
+  extra caps there rather than letting the next release quietly produce no downloads.
+- sphinx-gallery's own `.py`/`.zip` downloads still end up copied into `_downloads/`,
+  even though nothing on the page links to them anymore. Its `.ipynb` is never written:
+  with `gallery_downloads` on, this extension sets `sphinx_gallery_conf['pypandoc']` to
+  `False` and `sphinx_gallery_conf['notebook_extensions']` to an empty set before
+  sphinx-gallery reads them, so pandoc is not needed. Setting `pypandoc`,
+  `notebook_extensions`, `first_notebook_cell`, `last_notebook_cell` or `notebook_images`
+  yourself has no effect and is reported as a warning.
+
+## Development
+
+```bash
+uv sync --group dev --extra gallery
+uv run pytest
+uv run pre-commit run --all-files
+```

{sphinx_examples_as_code-0.6.1 → sphinx_examples_as_code-0.8.0}/pyproject.toml

@@ -4,6 +4,7 @@ requires = ['setuptools>=64', 'setuptools_scm>=8']
 
 [dependency-groups]
 dev = [
+  'marimo>=0.14',
   'nbformat',
   'numpydoc',
   'pre-commit',
@@ -31,7 +32,7 @@ classifiers = [
   'Programming Language :: Python :: 3.14',
   'Topic :: Scientific/Engineering :: Visualization',
 ]
-dependencies = ['pyvista>=0.48']
+dependencies = ['packaging>=22', 'pyvista>=0.48']
 description = 'Sphinx extension for converting docstring examples into downloadable code.'
 dynamic = ['version']
 keywords = ['download', 'examples', 'sphinx']
@@ -42,6 +43,7 @@ requires-python = '>=3.10'
 
 [project.optional-dependencies]
 gallery = ['sphinx-gallery>=0.22,<0.23']
+marimo = ['marimo>=0.14']
 
 [project.urls]
 Homepage = 'https://github.com/pyvista/sphinx-examples-as-code'