sphinx-exec-jupyter 0.1.0__tar.gz

sphinx_exec_jupyter-0.1.0/.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7

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

@@ -0,0 +1,87 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+env:
+  FORCE_COLOR: "1"
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  get-environments:
+    runs-on: ubuntu-latest
+    outputs:
+      envs: ${{ steps.get-envs.outputs.envs }}
+    steps:
+      - &CLONE
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 #v7.0.0
+        with:
+          filter: blob:none
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 #v8.2.0
+        with:
+          enable-cache: false
+      - id: get-envs
+        run: |
+          ENVS_JSON=$(NO_COLOR=1 uvx hatch env show --json | jq -c 'to_entries
+            | map(
+              select(.key | startswith("hatch-test"))
+              | { name: .key, python: .value.python }
+            )')
+          echo "envs=${ENVS_JSON}" | tee $GITHUB_OUTPUT
+  test:
+    needs: get-environments
+    permissions:
+      id-token: write  # for codecov OIDC
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        env: ${{ fromJSON(needs.get-environments.outputs.envs) }}
+    env:  # environment variable for use in codecov’s env_vars tagging
+      ENV_NAME: ${{ matrix.env.name }}
+    steps:
+      - *CLONE
+      - name: Install UV
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 #v8.2.0
+      - name: Install dependencies
+        run: uvx hatch -v env create ${{ matrix.env.name }}
+      - name: Run tests
+        run: |
+          uvx hatch run ${{ matrix.env.name }}:run-cov -v --color=yes -n auto --junitxml=test-results.xml
+          uvx hatch run ${{ matrix.env.name }}:cov-combine
+          uvx hatch run ${{ matrix.env.name }}:coverage xml
+          uvx hatch run ${{ matrix.env.name }}:cov-report
+      - name: Upload coverage data
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f #v7.0.0
+        with:
+          report_type: coverage
+          use_oidc: true
+          env_vars: ENV_NAME
+          fail_ci_if_error: true
+      - name: Upload test results
+        if: ${{ !cancelled() }}
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f #v7.0.0
+        with:
+          report_type: test_results
+          use_oidc: true
+          env_vars: ENV_NAME
+          fail_ci_if_error: true
+          files: test-results.xml
+  check:
+    if: always()
+    needs:
+      - get-environments
+      - test
+    runs-on: ubuntu-latest
+    steps:
+        - uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe #v1.2.2
+          with:
+            jobs: ${{ toJSON(needs) }}

sphinx_exec_jupyter-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: Publish Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions: {}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # to authenticate as Trusted Publisher to pypi.org
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 #v7.0.0
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 #v6.3.0
+        with:
+          python-version: "3.x"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b #v1.14.0

sphinx_exec_jupyter-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python
+__pycache__/
+/build/
+/dist/
+/.python-version
+
+# Testing
+/test-data/
+/.*cache/
+/.coverage*
+
+# Docs
+/docs/_build/
+
+# IDEs
+/.idea/

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

@@ -0,0 +1,29 @@
+ci:
+  autoupdate_commit_msg: "ci: pre-commit autoupdate"
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: no-commit-to-branch
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.18
+    hooks:
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-check
+        args: [--preview, --select=CPY]
+      - id: ruff-format
+  - repo: https://github.com/tox-dev/pyproject-fmt
+    rev: v2.25.0
+    hooks:
+      - id: pyproject-fmt
+  - repo: https://github.com/biomejs/pre-commit
+    rev: v2.5.0
+    hooks:
+      - id: biome-format
+  - repo: https://github.com/zizmorcore/zizmor-pre-commit
+    rev: v1.26.1
+    hooks:
+      - id: zizmor

sphinx_exec_jupyter-0.1.0/.readthedocs.yml

@@ -0,0 +1,15 @@
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    build:
+      html:
+        - uvx hatch run docs-build
+        - mv docs/_build $READTHEDOCS_OUTPUT

sphinx_exec_jupyter-0.1.0/.taplo.toml

@@ -0,0 +1,5 @@
+[formatting]
+array_auto_collapse = false
+column_width = 120
+compact_arrays = false
+indent_string = '  '

sphinx_exec_jupyter-0.1.0/.vscode/launch.json

@@ -0,0 +1,30 @@
+{
+	// https://go.microsoft.com/fwlink/?linkid=830387
+	"version": "0.2.0",
+	"configurations": [
+		{
+			"name": "Build Documentation",
+			"type": "debugpy",
+			"request": "launch",
+			"python": "${command:hatch.envInterpreter}", //always default env
+			"module": "sphinx",
+			"args": ["-M", "html", ".", "_build"],
+			"cwd": "${workspaceFolder}/docs",
+			"console": "internalConsole",
+			"justMyCode": false,
+		},
+		{
+			"name": "Debug test",
+			"type": "debugpy",
+			"request": "launch",
+			"program": "${file}",
+			"pythonArgs": ["-Xfrozen_modules=off"],
+			"console": "internalConsole",
+			"justMyCode": false,
+			"purpose": ["debug-test"],
+			"presentation": {
+				"hidden": true,
+			},
+		},
+	],
+}

sphinx_exec_jupyter-0.1.0/.vscode/settings.json

@@ -0,0 +1,22 @@
+{
+	"[toml][json][jsonc][python]": {
+		"editor.formatOnSave": true,
+	},
+	"[toml]": {
+		"editor.defaultFormatter": "tamasfe.even-better-toml",
+	},
+	"[json][jsonc]": {
+		"editor.defaultFormatter": "biomejs.biome",
+	},
+	"[python]": {
+		"editor.defaultFormatter": "charliermarsh.ruff",
+		"editor.codeActionsOnSave": {
+			"source.fixAll": "explicit",
+			"source.organizeImports": "explicit",
+		},
+	},
+	"python.testing.pytestEnabled": true,
+	"python.testing.pytestArgs": ["-vv", "--color=yes"],
+	"python-envs.defaultEnvManager": "pypa.hatch:hatch",
+	"python-envs.defaultPackageManager": "pypa.hatch:hatch",
+}

sphinx_exec_jupyter-0.1.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: sphinx-exec-jupyter
+Version: 0.1.0
+Summary: Execute code and let Jupyter format the output
+Project-URL: Documentation, https://sphinx-exec-jupyter.readthedocs.io/
+Project-URL: Source, https://github.com/flying-sheep/sphinx-exec-jupyter
+Author-email: "Philipp A." <flying-sheep@web.de>
+License-Expression: MPL-2.0
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Requires-Dist: myst-nb>=1.4
+Requires-Dist: nbformat>=5.10.4
+Requires-Dist: sphinx>=9.1
+Provides-Extra: holoviews
+Requires-Dist: holoviews; extra == 'holoviews'
+Requires-Dist: sphinx-design; extra == 'holoviews'

sphinx_exec_jupyter-0.1.0/README.md

@@ -0,0 +1,59 @@
+# sphinx-exec-jupyter
+
+[![Documentation Status][doc badge]][docs]
+[![Test Status][test badge]][tests]
+[![Coverage Status][codecov badge]][codecov]
+
+[doc badge]: https://readthedocs.org/projects/sphinx-exec-jupyter/badge/
+[docs]: https://sphinx-exec-jupyter.readthedocs.io/
+[test badge]: https://github.com/flying-sheep/sphinx-exec-jupyter/actions/workflows/ci.yml/badge.svg
+[tests]: https://github.com/flying-sheep/sphinx-exec-jupyter/actions/workflows/ci.yml
+[codecov badge]: https://codecov.io/gh/flying-sheep/sphinx-exec-jupyter/branch/main/graph/badge.svg
+[codecov]: https://codecov.io/gh/flying-sheep/sphinx-exec-jupyter
+
+This Sphinx extension allows you to execute Jupyter notebooks and include their output in your documentation.
+
+## Installation
+
+Install or depend on
+`sphinx-exec-jupyter @ git+https://github.com/flying-sheep/sphinx-exec-jupyter.git`,
+optionally with the `holoviews` extra (see below).
+Then enable this extension in your `conf.py`:
+
+```python
+extensions = [
+    "sphinx_exec_jupyter",
+]
+```
+
+## Directives
+
+### `exec-jupyter`
+
+Executes a Jupyter notebook cell and includes its output:
+
+```rst
+..  exec-jupyter::
+
+    import numpy as np
+    np.random.rand(4)
+```
+
+### `holoviews`
+
+Enable by installing the `holoviews` extra by depending on
+`sphinx-exec-jupyter[holoviews] @ git+https://github.com/flying-sheep/sphinx-exec-jupyter.git`
+
+Embeds a HoloViews plot:
+
+```rst
+..  holoviews::
+    :backends: bokeh,matplotlib
+
+    hv.Curve([1, 2, 3, 2, 1])
+```
+
+The default for `backends` is defined by a Sphinx `conf.py` setting:
+`holoviews_backends = ['bokeh']`
+
+For detailed documentation, visit [Read the Docs](https://sphinx-exec-jupyter.readthedocs.io/).

sphinx_exec_jupyter-0.1.0/biome.jsonc

@@ -0,0 +1,18 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.1.1/schema.json",
+	"formatter": { "useEditorconfig": true },
+	"overrides": [
+		{
+			"includes": ["./.vscode/*.json", "**/*.jsonc"],
+			"json": {
+				"formatter": {
+					"trailingCommas": "all",
+				},
+				"parser": {
+					"allowComments": true,
+					"allowTrailingCommas": true,
+				},
+			},
+		},
+	],
+}

sphinx_exec_jupyter-0.1.0/docs/conf.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: MPL-2.0
+"""Configuration for Sphinx documentation."""
+
+from __future__ import annotations
+
+from importlib.metadata import metadata
+
+_meta = metadata("sphinx-exec-jupyter")
+project = _meta["name"]
+author = _meta["author-email"].split('"')[1]
+release = _meta["version"]
+
+extensions = [
+    "sphinx_exec_jupyter",
+    "sphinx_design",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+master_doc = "index"
+
+html_theme = "furo"

sphinx_exec_jupyter-0.1.0/docs/index.rst

@@ -0,0 +1,122 @@
+``sphinx_exec_jupyter``
+=======================
+
+The ``sphinx-exec-jupyter`` Sphinx extension allows you to execute code
+in a Jupyter kernel and embed the output directly into your Sphinx documentation.
+
+This extension adds at least one directive (see `sphinx_exec_jupyter.holoviews`_ for more):
+
+..  rst:directive:: exec-jupyter
+
+    Execute a Jupyter notebook cell and embed the output into the documentation.
+    The Python expression on the last line of the directive body is displayed.
+
+It can be configured with the following settings:
+
+.. confval:: exec_jupyter_code
+    :type: ``str``
+
+    Prefix code to execute before the code in ``exec-jupyter`` or ``holoviews``.
+    Kernels are started from forked processes after this code is executed,
+    so it can be used for long-running initialization code (e.g. slow imports).
+
+.. confval:: exec_jupyter_kernel
+    :type: ``str``
+
+    Name of the Jupyter kernel to use.
+    If not set, the default kernel is used.
+
+.. confval:: exec_jupyter_patch_myst_nb
+    :type: ``bool``
+
+    If ``True`` (the default), and either ``exec_jupyter_code`` or ``exec_jupyter_kernel`` are set,
+    the ``myst_nb`` extension is patched to use the provided code and/or kernel.
+
+Examples
+--------
+
+.. code-block:: rst
+
+    ..  exec-jupyter::
+
+        import pandas as pd
+
+        pd.DataFrame(dict(
+            A=[1, 2, 3],
+            B=[4, 5, 6],
+        ))
+
+results in:
+
+..  exec-jupyter::
+
+    import pandas as pd
+
+    pd.DataFrame(dict(
+        A=[1, 2, 3],
+        B=[4, 5, 6],
+    ))
+
+``sphinx_exec_jupyter.holoviews``
+---------------------------------
+
+If you installed ``sphinx-exec-jupyter`` with the ``holoviews`` extra
+(e.g. ``pip install sphinx-exec-jupyter[holoviews]``),
+the ``sphinx_exec_jupyter.holoviews`` sub-extension is loaded automatically.
+
+This extension adds a setting and one more directive:
+
+..  confval:: holoviews_backends
+    :type: ``list[str]``
+    :default: ``['bokeh']``
+
+    A list of backends to use for rendering HoloViews plots.
+
+..  rst:directive:: holoviews
+
+    Embed a HoloViews plot into the documentation.
+    The Python expression on the last line of the directive body is displayed.
+
+    ..  rst:directive:option:: backends: backend1,backend2,...
+        :type: comma separated list of backends
+
+        The list of backends to use for rendering the plot. Defaults to :confval:`holoviews_backends`.
+
+..
+    See here for syntax:
+    https://www.sphinx-doc.org/en/master/usage/domains/restructuredtext.html#directive-rst-directive
+
+.. _holoviews-examples:
+
+Examples
+--------
+
+No options (defaults to bokeh):
+
+.. code-block:: rst
+
+    ..  holoviews::
+
+        hv.Curve([1, 2, 3, 2, 1])
+
+results in:
+
+..  holoviews::
+
+    hv.Curve([1, 2, 3, 2, 1])
+
+With multiple backends specified (needs the ``sphinx_design`` extension to be loaded):
+
+.. code-block:: rst
+
+    ..  holoviews::
+        :backends: bokeh,matplotlib,plotly
+
+        hv.Curve([1, 2, 3, 2, 1])
+
+results in:
+
+..  holoviews::
+    :backends: bokeh,matplotlib,plotly
+
+    hv.Curve([1, 2, 3, 2, 1])

sphinx_exec_jupyter-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = [ "hatch-vcs", "hatchling" ]
+
+[project]
+name = "sphinx-exec-jupyter"
+description = "Execute code and let Jupyter format the output"
+license = "MPL-2.0"
+authors = [ { name = "Philipp A.", email = "flying-sheep@web.de" } ]
+requires-python = ">=3.12"
+classifiers = [
+  "Framework :: Sphinx :: Extension",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+dynamic = [ "version" ]
+dependencies = [
+  "myst-nb>=1.4",
+  "nbformat>=5.10.4",
+  "sphinx>=9.1",
+]
+optional-dependencies.holoviews = [ "holoviews", "sphinx-design" ]
+urls.Documentation = "https://sphinx-exec-jupyter.readthedocs.io/"
+urls.Source = "https://github.com/flying-sheep/sphinx-exec-jupyter"
+entry-points."jupyter_client.kernel_provisioners".forking_provisioner = "sphinx_exec_jupyter._kernel_mgr:ForkingProvisioner"
+entry-points."myst_nb.mime_renderers".holoviews = "sphinx_exec_jupyter.holoviews:HoloViewsMimeRenderer"
+
+[tool.hatch]
+version.source = "vcs"
+envs.default.installer = "uv"
+envs.default.features = [ "holoviews" ]
+envs.default.dependencies = [ "furo", "matplotlib", "plotly" ]
+envs.default.scripts.docs-build = "sphinx-build -M html docs docs/_build {args:-W}"
+envs.default.scripts.docs-clean = "rm -rf docs/_build {args}"
+envs.default.scripts.docs-open = "python -m webbrowser docs/_build/html/index.html {args}"
+envs.hatch-test.features = [ "holoviews" ]
+envs.hatch-test.extra-dependencies = [ "anyio", "nbformat-types", "pytest-mock" ]
+envs.hatch-test.matrix = [
+  { python = [ "3.14", "3.12" ] },
+]
+
+[tool.ruff]
+lint.select = [ "ALL" ]
+lint.ignore = [
+  "C408",   # `dict()` is fine
+  "COM812", # conflict with formatter
+  "D203",
+  "D213",
+  "N999",   # Intentional dash in scripts not used for import
+  "S101",   # `assert` is fine
+  "TID252", # relative imports preferred
+]
+lint.per-file-ignores."**/*-*" = [
+  "PLC0415", # imports are not at the top for a reason
+  "T201",    # `print()` used for communication
+]
+lint.per-file-ignores."docs/**/*" = [ "INP001" ]
+lint.per-file-ignores."src/**/*" = [ "PT018" ]
+lint.per-file-ignores."tests/**/*" = [ "D", "INP001" ]
+lint.allowed-confusables = [ "×", "’" ]
+lint.flake8-copyright.notice-rgx = "SPDX-License-Identifier: MPL-2\\.0"
+lint.flake8-type-checking.exempt-modules = []
+lint.flake8-type-checking.strict = true
+lint.isort.required-imports = [ "from __future__ import annotations" ]
+
+[tool.pytest]
+addopts = [
+  "--import-mode=importlib",
+  "--doctest-modules",
+  "--pyargs",
+]
+anyio_mode = "auto"
+filterwarnings = [ "error" ]
+strict = true
+
+[tool.coverage]
+run.patch = [ "subprocess" ]
+run.source = [ "." ]

sphinx_exec_jupyter-0.1.0/src/sphinx_exec_jupyter/__init__.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: MPL-2.0
+"""Sphinx extension to run code snippets using Jupyter machinery."""
+
+from __future__ import annotations
+
+from contextlib import suppress
+from importlib.metadata import version
+from typing import TYPE_CHECKING
+
+from sphinx.errors import ExtensionError
+from sphinx.util.typing import ExtensionMetadata
+
+from ._directive import ExecJupyterDirective
+from ._kernel_mgr import maybe_patch_myst_nb
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.config import Config
+
+
+__all__ = ["ExecJupyterDirective", "setup"]
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    """Add directive(s) and settings to Sphinx."""
+    app.setup_extension("myst_nb")
+    app.add_config_value("exec_jupyter_code", "", "env")
+    app.add_config_value("exec_jupyter_kernel", "python3", "env")
+    app.add_config_value("exec_jupyter_patch_myst_nb", True, "env")  # noqa: FBT003
+    app.add_directive("exec-jupyter", ExecJupyterDirective)
+    app.connect("config-inited", _maybe_patch_myst_nb)
+
+    with suppress(ExtensionError):
+        app.setup_extension("sphinx_exec_jupyter.holoviews")
+
+    return ExtensionMetadata(
+        version=version("sphinx-exec-jupyter"),
+        parallel_read_safe=True,
+        parallel_write_safe=True,
+    )
+
+
+def _maybe_patch_myst_nb(app: Sphinx, config: Config) -> None:
+    ctx = maybe_patch_myst_nb(config)
+    ctx.__enter__()
+
+    def cleanup(app: Sphinx, exc: Exception | None) -> None:  # noqa: ARG001
+        if exc is None:
+            ctx.__exit__(None, None, None)
+        else:
+            ctx.__exit__(type(exc), exc, exc.__traceback__)
+
+    app.connect("build-finished", cleanup)

sphinx_exec_jupyter-0.1.0/src/sphinx_exec_jupyter/_directive.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: MPL-2.0
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sphinx.util.docutils import SphinxDirective
+
+from ._kernel_mgr import maybe_patch_myst_nb
+from .common import execute_cells
+
+if TYPE_CHECKING:
+    from docutils import nodes
+
+
+__all__ = ["ExecJupyterDirective"]
+
+
+class ExecJupyterDirective(SphinxDirective):
+    has_content = True
+
+    def run(self) -> list[nodes.Node]:
+        code = "\n".join(self.content)
+        with maybe_patch_myst_nb(self.config):
+            return execute_cells([code], self.state.document)