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

{sphinx_examples_as_code-0.2.1 → 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.1 → 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.1
+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.1 → 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.1 → 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]

{sphinx_examples_as_code-0.2.1 → sphinx_examples_as_code-0.3.0}/sphinx_examples_as_code/__init__.py

@@ -169,6 +169,21 @@ class _RenderContext:
     in_footer: bool = False
 
 
+def _normalized_html_baseurl(app: Sphinx) -> str | None:
+    """Sphinx's own ``html_baseurl`` config, normalized for use with ``urljoin``.
+
+    ``None`` if unset or not a usable absolute URL. Adds a missing trailing
+    slash.
+    """
+    base_url = app.config.html_baseurl
+    if not base_url:
+        return None
+    parsed = urlsplit(base_url)
+    if parsed.scheme not in ('http', 'https') or not parsed.netloc:
+        return None
+    return base_url if base_url.endswith('/') else base_url + '/'
+
+
 def _resolve_link_url(node: nodes.reference, ctx: _RenderContext) -> str | None:
     """Resolve a reference node's target to an absolute URL, if possible.
 
@@ -181,7 +196,7 @@ def _resolve_link_url(node: nodes.reference, ctx: _RenderContext) -> str | None:
     if refuri and urlsplit(refuri).netloc:
         return refuri  # already absolute (an external hyperlink)
 
-    base_url = ctx.app.config.sphinx_examples_as_code_conf['base_url']
+    base_url = _normalized_html_baseurl(ctx.app)
     if not base_url:
         return None
     current_page_url = urljoin(base_url, ctx.app.builder.get_target_uri(ctx.docname))
@@ -353,18 +368,42 @@ def _convert_literal_block(node: nodes.literal_block) -> list[Segment]:
     return [('directive', comment_lines)]
 
 
-def _title_underline_segment(title: str) -> Segment:
-    """Build a title + underline directive segment, e.g. ``# Title`` + ``# -----``.
+#: Setext underline character per heading level -- ``=`` for the file's own
+#: top-level header (level 1), ``-`` for a subheading (level 2). CommonMark's
+#: setext syntax only supports these two levels.
+_TITLE_UNDERLINE_CHARS = {1: '=', 2: '-'}
+
 
-    Shared by the file's own header (see ``_header_segment``) and gallery
-    mode's sibling-section headings. The underline is what makes this render
-    as a real Markdown heading in ``.ipynb`` (setext-style, once the ``#``
-    comment prefix is stripped for markdown cells) rather than plain text.
+def _title_underline_segment(title: str, level: int = 1) -> Segment:
+    """Build a title + underline directive segment, e.g. ``# Title`` + ``# =====``.
+
+    Shared by the file's own header (see ``_header_segment``), which is
+    always level 1, and gallery mode's sibling-section headings, which are
+    level 2. The underline is what makes this render as a real Markdown
+    heading in ``.ipynb`` (setext-style, once the ``#`` comment prefix is
+    stripped for markdown cells) rather than plain text.
     """
-    underline = '-' * len(title)
+    underline = _TITLE_UNDERLINE_CHARS[level] * len(title)
     return ('directive', [f'# {title}', f'# {underline}'])
 
 
+def _heading_level(title: nodes.title) -> int:
+    """Compute a title's heading level from its ``nodes.section`` nesting depth.
+
+    Counts the title's own section and each ancestor ``nodes.section``.
+    Running this on the file's own header would give level 1; a title
+    nested inside that comes out level 2, and so does anything nested
+    deeper (clamped -- the deepest level CommonMark's setext syntax can
+    represent).
+    """
+    level = 0
+    node: nodes.Node | None = title.parent
+    while isinstance(node, nodes.section):
+        level += 1
+        node = node.parent
+    return min(level, 2)
+
+
 def _convert_admonition(
     node: nodes.Element, label: str, ctx: _RenderContext, *, skip_first_title: bool = False
 ) -> list[Segment]:
@@ -403,12 +442,12 @@ def _convert_node(node: nodes.Node, ctx: _RenderContext) -> list[Segment]:
     if isinstance(node, nodes.title):
         # Gallery mode only: a sibling section's own heading (the page's own
         # outer title is filtered out before reaching here -- see
-        # _process_gallery_page). Same title+underline treatment as the
-        # file's own header, so it reads as a real heading -- and renders as
-        # an actual Markdown heading in .ipynb -- instead of melting into
-        # whatever prose follows it with no visual break.
+        # _process_gallery_page). Renders as a real Markdown heading in
+        # .ipynb, at a level relative to its own section nesting (see
+        # _heading_level).
         title_text = _render_inline(node, ctx).strip()
-        return [_title_underline_segment(title_text)] if title_text else []
+        level = _heading_level(node)
+        return [_title_underline_segment(title_text, level=level)] if title_text else []
     if isinstance(node, (*_CONTAINER_TYPES, nodes.section)):
         # nodes.section (gallery mode only): a sphinx-gallery ``# %%`` cell
         # with its own RST heading becomes a *sibling* section at the
@@ -699,12 +738,13 @@ def _write_notebook(app: Sphinx, name: str, notebook: dict) -> str:
     return _write_download_file(app, name, 'ipynb', json.dumps(notebook, indent=1))
 
 
-#: Download link text per format, and the fixed order they're offered in
-#: regardless of how ``sphinx_examples_as_code_conf['formats']`` lists them.
-_FORMAT_LABELS = {
+#: Default download link text per format -- see ``sphinx_examples_as_code_conf['link_labels']``.
+_DEFAULT_LINK_LABELS = {
     'py': 'Download Python source code',
     'ipynb': 'Download Jupyter notebook',
 }
+#: The fixed order formats are offered in, regardless of how
+#: ``sphinx_examples_as_code_conf['formats']`` lists them.
 _FORMAT_ORDER = ('py', 'ipynb')
 
 
@@ -749,6 +789,7 @@ def _build_download_entries(
     nodes_in_span: list[nodes.Node],
     formats: list[str],
     footer: str | None,
+    link_labels: dict[str, str],
 ) -> list[tuple[str, str]]:
     """Convert a span of nodes into written ``.py``/``.ipynb`` files, per ``formats``.
 
@@ -775,7 +816,7 @@ def _build_download_entries(
     for fmt in _FORMAT_ORDER:
         if fmt not in formats:
             continue
-        label = _FORMAT_LABELS[fmt]
+        label = link_labels[fmt]
         if fmt == 'py':
             rel_path = _write_source(app, name, source)
         else:
@@ -807,6 +848,7 @@ def _process_span(
     position: str,
     formats: list[str],
     footer: str | None,
+    link_labels: dict[str, str],
 ) -> None:
     """Convert one Examples span and insert download link(s) if it has real code."""
     nodes_in_span = list(parent.children[start:end])
@@ -816,7 +858,7 @@ def _process_span(
 
     name = _qualified_name_for(heading, docname, counter)
     entries = _build_download_entries(
-        app, docname, name, _header_segment(name), nodes_in_span, formats, footer
+        app, docname, name, _header_segment(name), nodes_in_span, formats, footer, link_labels
     )
     if not entries:
         return
@@ -900,6 +942,7 @@ def _process_gallery_page(
     position: str,
     formats: list[str],
     footer: str | None,
+    link_labels: dict[str, str],
 ) -> None:
     """Replace a sphinx-gallery page's own download footer with converted downloads.
 
@@ -936,7 +979,9 @@ def _process_gallery_page(
     # no "from" framing to make. Falls back to the usual header on the off
     # chance the page has no title of its own.
     header = _title_underline_segment(title) if title else _header_segment(name)
-    entries = _build_download_entries(app, docname, name, header, nodes_in_span, formats, footer)
+    entries = _build_download_entries(
+        app, docname, name, header, nodes_in_span, formats, footer, link_labels
+    )
     if not entries:
         return
 
@@ -960,9 +1005,10 @@ def _process_doctree(app: Sphinx, doctree: nodes.document, docname: str) -> None
     position = conf['link_position']
     formats = conf['formats']
     footer = conf['footer']
+    link_labels = conf['link_labels']
 
     if conf['gallery_downloads']:
-        _process_gallery_page(app, docname, doctree, position, formats, footer)
+        _process_gallery_page(app, docname, doctree, position, formats, footer, link_labels)
 
     # Process spans per shared parent, last to first: inserting a download
     # node shifts every later sibling index by one, so this stays correct
@@ -972,7 +1018,19 @@ def _process_doctree(app: Sphinx, doctree: nodes.document, docname: str) -> None
     for parent, start, end, heading, counter in sorted(
         numbered_spans, key=lambda s: (id(s[0]), -s[1])
     ):
-        _process_span(app, docname, parent, start, end, heading, counter, position, formats, footer)
+        _process_span(
+            app,
+            docname,
+            parent,
+            start,
+            end,
+            heading,
+            counter,
+            position,
+            formats,
+            footer,
+            link_labels,
+        )
 
 
 # One line, one link: a second sentence pointing at the issue tracker read
@@ -989,33 +1047,12 @@ _DEFAULT_FOOTER = (
 _CONF_DEFAULTS: dict[str, object] = {
     'link_position': 'top',
     'formats': ['py', 'ipynb'],
-    'base_url': None,
     'gallery_downloads': False,
     'footer': _DEFAULT_FOOTER,
+    'link_labels': _DEFAULT_LINK_LABELS,
 }
 
 
-def _normalize_base_url(base_url: str | None) -> str | None:
-    """Validate and normalize a ``base_url`` value.
-
-    Catches two common typos loudly instead of silently generating wrong
-    links: a missing scheme (parses with no netloc at all), and a subpath
-    with no trailing slash (``urljoin`` would drop the last segment).
-    """
-    if not base_url:
-        return None
-
-    parsed = urlsplit(base_url)
-    if parsed.scheme not in ('http', 'https') or not parsed.netloc:
-        msg = (
-            f"sphinx_examples_as_code_conf['base_url']={base_url!r} does not look "
-            "like a valid absolute URL (expected something like 'https://docs.example.com/')."
-        )
-        raise ConfigError(msg)
-
-    return base_url if base_url.endswith('/') else base_url + '/'
-
-
 def _coerce_conf_value(key: str, value: object) -> object:
     """Coerce a value that may have arrived as a raw string; pass anything else through.
 
@@ -1039,7 +1076,27 @@ def _coerce_conf_value(key: str, value: object) -> object:
             f"sphinx_examples_as_code_conf['gallery_downloads'] must be '0' or '1', got {value!r}."
         )
         raise ConfigError(msg)
-    return value  # link_position, base_url, footer: a string is already the real type
+    return value  # link_position, footer: a string is already the real type
+
+
+def _merged_link_labels(value: object) -> dict[str, str]:
+    """Merge a user-provided ``link_labels`` override over the defaults.
+
+    A partial override (e.g. just ``{'py': 'Get the script'}``) only changes
+    that one format's label; any not given keep their default.
+    """
+    if not isinstance(value, dict):
+        msg = f"sphinx_examples_as_code_conf['link_labels'] must be a dict, got {value!r}."
+        raise ConfigError(msg)
+    unknown = sorted(set(value) - set(_DEFAULT_LINK_LABELS))
+    if unknown:
+        valid = ', '.join(sorted(_DEFAULT_LINK_LABELS))
+        msg = (
+            f"sphinx_examples_as_code_conf['link_labels'] has unknown key(s) {unknown} "
+            f'(valid keys: {valid}).'
+        )
+        raise ConfigError(msg)
+    return {**_DEFAULT_LINK_LABELS, **value}
 
 
 def _finalize_conf(_app: Sphinx, config: Config) -> None:
@@ -1059,7 +1116,7 @@ def _finalize_conf(_app: Sphinx, config: Config) -> None:
 
     merged = dict(_CONF_DEFAULTS)
     merged.update((key, _coerce_conf_value(key, value)) for key, value in user_conf.items())
-    merged['base_url'] = _normalize_base_url(merged['base_url'])
+    merged['link_labels'] = _merged_link_labels(merged['link_labels'])
     config.sphinx_examples_as_code_conf = merged