sphinx-examples-as-code 0.2.0__tar.gz → 0.3.0__tar.gz

{sphinx_examples_as_code-0.2.0 → sphinx_examples_as_code-0.3.0}/.github/workflows/ci.yml

@@ -86,4 +86,4 @@ jobs:
       with:
         name: dist
         path: dist/
-    - uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247   # release/v1
+    - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33   # release/v1

sphinx_examples_as_code-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2026 The PyVista Developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

{sphinx_examples_as_code-0.2.0 → sphinx_examples_as_code-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-examples-as-code
-Version: 0.2.0
+Version: 0.3.0
 Summary: Sphinx extension for converting docstring examples into downloadable code.
 Author-email: The PyVista Developers <info@pyvista.org>
 License-Expression: MIT
@@ -21,7 +21,9 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: pyvista>=0.48
+Dynamic: license-file
 
 # sphinx-examples-as-code
 
@@ -55,12 +57,15 @@ the keys you want to change from their default:
 sphinx_examples_as_code_conf = {
     'link_position': 'top',
     'formats': ['py', 'ipynb'],
-    'base_url': None,
     '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',
+    },
 }
 ```
 
@@ -68,29 +73,26 @@ sphinx_examples_as_code_conf = {
   (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.
-- `base_url`: the site's published base URL (e.g. `'https://docs.pyvista.org/'`), used
-  to turn cross-references into absolute links a downloaded, standalone file can
-  actually use. `None` (default) means no links are generated anywhere. A missing
-  trailing slash is added automatically; a value with no scheme or host raises a
-  configuration error at build start.
+- `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, marking it as trailing
-  boilerplate rather than more of the example's own commentary -- the divider also
-  renders as a real horizontal rule in `.ipynb`, where the footer always gets its own
-  dedicated cell, regardless of what content precedes it. Parsed as RST, the same as any
-  other prose this extension handles: 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 -- a longer, multi-paragraph custom
-  footer is laid out the same way any other prose in this extension is.
-
-An unrecognized key (a typo, or a leftover from an older release) raises a configuration
-error at build start rather than silently doing nothing.
+  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.
+  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.
+
+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
@@ -103,16 +105,14 @@ 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 -- so a
-  preformatted block (e.g. an RST `::`-block illustrating a data format) still reads as
-  a distinct block rather than melting into the surrounding prose.
+  comments, set off with blank lines on both sides like any other directive.
 - Admonitions (`.. note::`, `.. warning::`, `.. seealso::`, ...) become a `# LABEL:`
   comment followed by their content as comments. "See Also" is recognized in any of its
   three forms (`.. seealso::`, a bare `.. rubric:: See Also`, or a hand-written `See
   Also` heading) and always renders the same way.
 - 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 `base_url` is set and
+  ``:class:`pyvista.Plotter` `` -> `` `pyvista.Plotter` ``). If `html_baseurl` is set and
   the reference resolves: `.ipynb` turns it into a clickable link everywhere; `.py` only
   writes the link inside a "See Also" part (as `name url` on its own line) — everywhere
   else in `.py` the link is simply omitted.
@@ -121,15 +121,13 @@ What happens to the content of an Examples section:
 - Everything else text-bearing (prose, captions, other non-Python code) becomes a plain
   `#` comment.
 - Figures/images, raw HTML, sphinx-design dropdowns/tab-sets, and sphinx-tags' `.. tags::`
-  line are dropped entirely -- none of them are documentation content a downloaded,
-  standalone file has any use for.
+  line are dropped entirely.
 
 Generated `.py` files start with a `# Examples from <qualified name>` title header
-(gallery mode uses the page's own title instead -- see below) and follow a few
-whitespace conventions so the result reads like normal Python: 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.
+(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
 cells instead.
@@ -146,35 +144,30 @@ full example code" note and the `.py`/`.ipynb`/`.zip` download footer are remove
 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>` — gallery mode converts the whole
-page, not an Examples section carved out of a larger docstring, so there's no "from"
-framing to make.
+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: a "Total running time" sitting inside a file you just downloaded and ran
-yourself would read like it's timing *your* run, not the build's, and a "Generated by
-Sphinx-Gallery" credit is simply wrong inside a file this extension generated.
+itself.
 
 Detection is automatic and per-page — any page without a sphinx-gallery download footer
-is left completely untouched, so turning this on is safe even on a site that mixes
-gallery pages with ordinary docstring/prose pages using the Examples-section behavior
-above.
+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 title-plus-underline treatment as
-the file's own header, rather than melting into whatever prose follows it -- and for
-that reason renders as a real Markdown heading in `.ipynb`, not just plain text.
+the file's own header, and renders as a real Markdown heading in `.ipynb` (`<h1>` for the
+file's own header, `# Title` + `# ====`; `<h2>` for a cell heading, `# Title` + `# ----`).
+A cell heading nested under the page's own title (the common case) is level 2; one that
+reuses the page title's own underline character -- a real RST heading, one level up --
+is level 1, matching the file's own header.
 
 Two things worth knowing before turning this on:
 
-- It's built against sphinx-gallery's own long-standing RST/HTML output (the same
-  `sphx-glr-*` CSS classes its own theming depends on), not a documented extension API.
-  It's unlikely to change, but a future sphinx-gallery release could still shift that
-  structure without warning.
-- sphinx-gallery registers its own `.py`/`.ipynb`/`.zip` downloads for copying into
-  `_downloads/` before this extension gets a chance to remove the links pointing to
-  them, so those files still end up in the build output even though nothing on the page
-  links to them anymore.
+- It's built against sphinx-gallery's own RST/HTML output (the same `sphx-glr-*` CSS
+  classes its own theming depends on), not a documented extension API. A future
+  sphinx-gallery release could shift that structure without warning.
+- sphinx-gallery's own `.py`/`.ipynb`/`.zip` downloads still end up copied into
+  `_downloads/`, even though nothing on the page links to them anymore.
 
 ## Development
 

{sphinx_examples_as_code-0.2.0 → sphinx_examples_as_code-0.3.0}/README.md

@@ -30,12 +30,15 @@ the keys you want to change from their default:
 sphinx_examples_as_code_conf = {
     'link_position': 'top',
     'formats': ['py', 'ipynb'],
-    'base_url': None,
     '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',
+    },
 }
 ```
 
@@ -43,29 +46,26 @@ sphinx_examples_as_code_conf = {
   (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.
-- `base_url`: the site's published base URL (e.g. `'https://docs.pyvista.org/'`), used
-  to turn cross-references into absolute links a downloaded, standalone file can
-  actually use. `None` (default) means no links are generated anywhere. A missing
-  trailing slash is added automatically; a value with no scheme or host raises a
-  configuration error at build start.
+- `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, marking it as trailing
-  boilerplate rather than more of the example's own commentary -- the divider also
-  renders as a real horizontal rule in `.ipynb`, where the footer always gets its own
-  dedicated cell, regardless of what content precedes it. Parsed as RST, the same as any
-  other prose this extension handles: 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 -- a longer, multi-paragraph custom
-  footer is laid out the same way any other prose in this extension is.
-
-An unrecognized key (a typo, or a leftover from an older release) raises a configuration
-error at build start rather than silently doing nothing.
+  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.
+  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.
+
+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
@@ -78,16 +78,14 @@ 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 -- so a
-  preformatted block (e.g. an RST `::`-block illustrating a data format) still reads as
-  a distinct block rather than melting into the surrounding prose.
+  comments, set off with blank lines on both sides like any other directive.
 - Admonitions (`.. note::`, `.. warning::`, `.. seealso::`, ...) become a `# LABEL:`
   comment followed by their content as comments. "See Also" is recognized in any of its
   three forms (`.. seealso::`, a bare `.. rubric:: See Also`, or a hand-written `See
   Also` heading) and always renders the same way.
 - 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 `base_url` is set and
+  ``:class:`pyvista.Plotter` `` -> `` `pyvista.Plotter` ``). If `html_baseurl` is set and
   the reference resolves: `.ipynb` turns it into a clickable link everywhere; `.py` only
   writes the link inside a "See Also" part (as `name url` on its own line) — everywhere
   else in `.py` the link is simply omitted.
@@ -96,15 +94,13 @@ What happens to the content of an Examples section:
 - Everything else text-bearing (prose, captions, other non-Python code) becomes a plain
   `#` comment.
 - Figures/images, raw HTML, sphinx-design dropdowns/tab-sets, and sphinx-tags' `.. tags::`
-  line are dropped entirely -- none of them are documentation content a downloaded,
-  standalone file has any use for.
+  line are dropped entirely.
 
 Generated `.py` files start with a `# Examples from <qualified name>` title header
-(gallery mode uses the page's own title instead -- see below) and follow a few
-whitespace conventions so the result reads like normal Python: 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.
+(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
 cells instead.
@@ -121,35 +117,30 @@ full example code" note and the `.py`/`.ipynb`/`.zip` download footer are remove
 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>` — gallery mode converts the whole
-page, not an Examples section carved out of a larger docstring, so there's no "from"
-framing to make.
+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: a "Total running time" sitting inside a file you just downloaded and ran
-yourself would read like it's timing *your* run, not the build's, and a "Generated by
-Sphinx-Gallery" credit is simply wrong inside a file this extension generated.
+itself.
 
 Detection is automatic and per-page — any page without a sphinx-gallery download footer
-is left completely untouched, so turning this on is safe even on a site that mixes
-gallery pages with ordinary docstring/prose pages using the Examples-section behavior
-above.
+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 title-plus-underline treatment as
-the file's own header, rather than melting into whatever prose follows it -- and for
-that reason renders as a real Markdown heading in `.ipynb`, not just plain text.
+the file's own header, and renders as a real Markdown heading in `.ipynb` (`<h1>` for the
+file's own header, `# Title` + `# ====`; `<h2>` for a cell heading, `# Title` + `# ----`).
+A cell heading nested under the page's own title (the common case) is level 2; one that
+reuses the page title's own underline character -- a real RST heading, one level up --
+is level 1, matching the file's own header.
 
 Two things worth knowing before turning this on:
 
-- It's built against sphinx-gallery's own long-standing RST/HTML output (the same
-  `sphx-glr-*` CSS classes its own theming depends on), not a documented extension API.
-  It's unlikely to change, but a future sphinx-gallery release could still shift that
-  structure without warning.
-- sphinx-gallery registers its own `.py`/`.ipynb`/`.zip` downloads for copying into
-  `_downloads/` before this extension gets a chance to remove the links pointing to
-  them, so those files still end up in the build output even though nothing on the page
-  links to them anymore.
+- It's built against sphinx-gallery's own RST/HTML output (the same `sphx-glr-*` CSS
+  classes its own theming depends on), not a documented extension API. A future
+  sphinx-gallery release could shift that structure without warning.
+- sphinx-gallery's own `.py`/`.ipynb`/`.zip` downloads still end up copied into
+  `_downloads/`, even though nothing on the page links to them anymore.
 
 ## Development
 

{sphinx_examples_as_code-0.2.0 → sphinx_examples_as_code-0.3.0}/pyproject.toml

@@ -96,6 +96,7 @@ ignore = ['D203', 'D211', 'D213']
 # sphinx-gallery example scripts: the module docstring is an RST page title
 # (title line + underline), not prose -- pydocstyle's summary-line rules don't apply.
 'tests/gallery_fixture/examples/*' = ['D205', 'D400', 'D415', 'T201']
+'tests/heading_level_fixture/examples/*' = ['D205', 'D400', 'D415', 'T201']
 
 [tool.ruff.lint.isort]
 combine-as-imports = true
@@ -104,6 +105,7 @@ force-sort-within-sections = true
 required-imports = ['from __future__ import annotations']
 
 [tool.setuptools]
+license-files = ['LICENSE']
 packages = ['sphinx_examples_as_code']
 
 [tool.setuptools_scm]