sphinx-examples-as-code 0.1.0__tar.gz

sphinx_examples_as_code-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+- package-ecosystem: pip
+  directory: /
+  schedule:
+    interval: weekly
+  labels: [maintenance, dependencies]
+  open-pull-requests-limit: 20
+- package-ecosystem: github-actions
+  directory: /.github/workflows
+  schedule:
+    interval: weekly
+  labels: [maintenance, dependencies]
+  groups:
+    artifacts:
+      patterns: [actions/upload-artifact, actions/download-artifact]

sphinx_examples_as_code-0.1.0/.github/release.yml

@@ -0,0 +1,9 @@
+changelog:
+  exclude:
+    authors:
+    - dependabot
+    - dependabot[bot]
+    - pre-commit-ci
+    - pre-commit-ci[bot]
+    - github-actions
+    - github-actions[bot]

sphinx_examples_as_code-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,89 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: [v*]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1   # v7.0.1
+      with:
+        persist-credentials: false
+        fetch-depth: 0
+    - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9   # v9.0.0
+      with:
+        enable-cache: false
+    - run: uv sync --group dev
+    - run: uv run pre-commit run --all-files --show-diff-on-failure
+      env:
+          # This hook exists to stop *local* commits straight to main; it
+          # would always fail here since CI checks out that branch/tag directly.
+        SKIP: no-commit-to-branch
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1   # v7.0.1
+      with:
+        persist-credentials: false
+        fetch-depth: 0
+    - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9   # v9.0.0
+      with:
+        enable-cache: false
+    - uses: pyvista/setup-headless-display-action@5bc8de3bc71fcda7a96439571287a554901541a0   # v4.3
+      with:
+        pyvista: true
+    - run: uv sync --group dev --python ${{ matrix.python-version }}
+    - run: uv run pytest tests/ --cov --cov-report=xml
+    - uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f   # v7.0.0
+      with:
+        files: ./coverage.xml
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  build:
+    needs: [pre-commit, test]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1   # v7.0.1
+      with:
+        persist-credentials: false
+        fetch-depth: 0
+    - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9   # v9.0.0
+      with:
+        enable-cache: false
+    - run: uv build
+    - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a   # v7.0.1
+      with:
+        name: dist
+        path: dist/
+
+  publish:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+    - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c   # v8.0.1
+      with:
+        name: dist
+        path: dist/
+    - uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247   # release/v1

sphinx_examples_as_code-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+.coverage
+.idea/
+*.egg-info/
+__pycache__/
+sphinx_examples_as_code/_version.py

sphinx_examples_as_code-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,38 @@
+ci:
+  autoupdate_commit_msg: 'chore: update pre-commit hooks'
+  autofix_prs: true
+  autoupdate_schedule: quarterly
+
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v5.0.0
+  hooks:
+  - id: check-merge-conflict
+  - id: debug-statements
+  - id: no-commit-to-branch
+    args: [--branch, main]
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.16.0
+  hooks:
+  - id: ruff-check
+    args: [--fix, --show-fixes]
+  - id: ruff-format
+
+- repo: https://github.com/zizmorcore/zizmor-pre-commit
+  rev: v1.11.0
+  hooks:
+  - id: zizmor
+
+- repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
+  rev: v2.15.0
+  hooks:
+  - id: pretty-format-yaml
+    args: [--autofix, --indent, '2']
+
+- repo: https://github.com/ComPWA/taplo-pre-commit
+  rev: v0.9.3
+  hooks:
+  - id: taplo-format
+      # See options: https://taplo.tamasfe.dev/configuration/formatter-options.html
+    args: [--option, reorder_arrays=true, --option, reorder_keys=true, --option, align_comments=false]

sphinx_examples_as_code-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: sphinx-examples-as-code
+Version: 0.1.0
+Summary: Sphinx extension for converting docstring examples into downloadable code.
+Author-email: The PyVista Developers <info@pyvista.org>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pyvista/sphinx-examples-as-code
+Keywords: download,examples,sphinx
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyvista>=0.48
+
+# 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.
+
+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
+```
+
+Add it to your Sphinx `conf.py`:
+
+```python
+extensions = [
+    ...,
+    'sphinx_examples_as_code',
+]
+```
+
+## Configuration
+
+Set these in `conf.py`:
+
+- `sphinx_examples_as_code_link_position`: where the download link(s) land within the
+  Examples section. `'top'` (default) or `'bottom'`.
+- `sphinx_examples_as_code_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.
+- `sphinx_examples_as_code_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.
+
+## 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.
+- 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
+  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.
+- 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.
+- Figures/images, raw HTML, and sphinx-design dropdowns/tab-sets are dropped entirely.
+
+Generated `.py` files start with a `# Examples from <qualified name>` title header 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.
+
+Generated `.ipynb` notebooks use the same content, split into alternating code/markdown
+cells instead.
+
+A download link is only added if the resulting code contains at least one real
+executable statement.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run pre-commit run --all-files
+```

sphinx_examples_as_code-0.1.0/README.md

@@ -0,0 +1,81 @@
+# 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.
+
+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
+```
+
+Add it to your Sphinx `conf.py`:
+
+```python
+extensions = [
+    ...,
+    'sphinx_examples_as_code',
+]
+```
+
+## Configuration
+
+Set these in `conf.py`:
+
+- `sphinx_examples_as_code_link_position`: where the download link(s) land within the
+  Examples section. `'top'` (default) or `'bottom'`.
+- `sphinx_examples_as_code_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.
+- `sphinx_examples_as_code_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.
+
+## 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.
+- 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
+  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.
+- 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.
+- Figures/images, raw HTML, and sphinx-design dropdowns/tab-sets are dropped entirely.
+
+Generated `.py` files start with a `# Examples from <qualified name>` title header 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.
+
+Generated `.ipynb` notebooks use the same content, split into alternating code/markdown
+cells instead.
+
+A download link is only added if the resulting code contains at least one real
+executable statement.
+
+## Development
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run pre-commit run --all-files
+```

sphinx_examples_as_code-0.1.0/pyproject.toml

@@ -0,0 +1,107 @@
+[build-system]
+build-backend = 'setuptools.build_meta'
+requires = ['setuptools>=64', 'setuptools_scm>=8']
+
+[dependency-groups]
+dev = [
+  'nbformat',
+  'numpydoc',
+  'pre-commit',
+  'pytest',
+  'pytest-cov',
+  'sphinx',
+  'sphinx-design',
+  'trame-pyvista',
+]
+
+[project]
+authors = [{ name = 'The PyVista Developers', email = 'info@pyvista.org' }]
+classifiers = [
+  'Development Status :: 4 - Beta',
+  'Framework :: Sphinx :: Extension',
+  'Intended Audience :: Science/Research',
+  'Operating System :: MacOS',
+  'Operating System :: Microsoft :: Windows',
+  'Operating System :: POSIX :: Linux',
+  'Programming Language :: Python :: 3',
+  'Programming Language :: Python :: 3.10',
+  'Programming Language :: Python :: 3.11',
+  'Programming Language :: Python :: 3.12',
+  'Programming Language :: Python :: 3.13',
+  'Programming Language :: Python :: 3.14',
+  'Topic :: Scientific/Engineering :: Visualization',
+]
+dependencies = ['pyvista>=0.48']
+description = 'Sphinx extension for converting docstring examples into downloadable code.'
+dynamic = ['version']
+keywords = ['download', 'examples', 'sphinx']
+license = 'MIT'
+name = 'sphinx-examples-as-code'
+readme = 'README.md'
+requires-python = '>=3.10'
+
+[project.urls]
+Homepage = 'https://github.com/pyvista/sphinx-examples-as-code'
+
+[tool.coverage.run]
+branch = true
+omit = ['*/_version.py']
+parallel = true
+source = ['sphinx_examples_as_code']
+
+[tool.pytest.ini_options]
+addopts = '--cov=sphinx_examples_as_code --cov-fail-under=95'
+testpaths = 'tests'
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.format]
+quote-style = 'single'
+
+[tool.ruff.lint]
+extend-select = [
+  'A',
+  'B',
+  'C4',
+  'D',
+  'E',
+  'EM',
+  'F',
+  'FA',
+  'I',
+  'ICN',
+  'N',
+  'PERF',
+  'PGH',
+  'PIE',
+  'PT',
+  'RET',
+  'RSE',
+  'RUF',
+  'SIM',
+  'T10',
+  'T20',
+  'TCH',
+  'TID',
+  'UP',
+  'W',
+  'YTT',
+]
+ignore = ['D203', 'D211', 'D213']
+[tool.ruff.lint.per-file-ignores]
+'*/conf.py' = ['E402']
+'tests/*' = ['D103']
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+force-single-line = true
+force-sort-within-sections = true
+required-imports = ['from __future__ import annotations']
+
+[tool.setuptools]
+packages = ['sphinx_examples_as_code']
+
+[tool.setuptools_scm]
+version_scheme = 'release-branch-semver'
+write_to = 'sphinx_examples_as_code/_version.py'

sphinx_examples_as_code-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+