mkdocs-jupyterlite 0.1.0__tar.gz

mkdocs_jupyterlite-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: docs 
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email github-actions[bot]@users.noreply.github.com
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      
+      - name: Install UV
+        run: curl -LsSf https://astral.sh/uv/0.4.18/install.sh | sh
+
+      - run: uv run mkdocs gh-deploy

mkdocs_jupyterlite-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+
+name: publish 
+on:
+  workflow_dispatch:
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/<your-pypi-project-name>
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+        with:
+            fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+            python-version: "3.13"
+        
+      - name: Install UV
+        run: curl -LsSf https://astral.sh/uv/0.4.18/install.sh | sh
+
+      - name: Build package distributions
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mkdocs_jupyterlite-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+site
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

mkdocs_jupyterlite-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: mkdocs-jupyterlite
+Version: 0.1.0
+Summary: Embed interactive JupyterLite notebooks in your MkDocs site.
+Project-URL: Documentation, https://github.com/NickCrews/mkdocs-jupyterlite#readme
+Project-URL: Homepage, https://github.com/NickCrews/mkdocs-jupyterlite
+Project-URL: Source, https://github.com/NickCrews/mkdocs-jupyterlite
+Project-URL: Tracker, https://github.com/NickCrews/mkdocs-jupyterlite/issues
+Author-email: Nick Crews <nicholas.b.crews@gmail.com>
+Requires-Python: >=3.10
+Requires-Dist: jupyterlab-server>=2.27.3
+Requires-Dist: jupyterlite-core>=0.6.4
+Requires-Dist: jupyterlite-pyodide-kernel>=0.6.1
+Requires-Dist: mkdocs>=1.6.1
+Description-Content-Type: text/markdown
+
+# mkdocs-jupyterlite
+
+A MkDocs plugin that enables embedding interactive jupyterlite notebooks in your docs.
+
+Say you have a notebook `example.ipynb` in your awesome project, and you want
+users to be able to play around with it.
+In the past, you could use a tool like [Binder](https://mybinder.org/) to achieve this.
+But, that requires a full docker environment and a remote server.
+By using [JupyterLite](https://jupyterlite.readthedocs.io/),
+you can run Jupyter notebooks directly in the browser without any server-side dependencies.
+
+However, to use jupyterlite, you have to manually install jupyterlite and
+then run a build step to package your notebooks, other files, and python
+dependencies into a single static site.
+
+This plugin automates that process for you.
+
+## Installation
+
+1. Install the plugin
+
+```bash
+pip install mkdocs-jupyterlite
+```
+
+2. Configure in your `mkdocs.yml` file
+
+```yaml
+plugins:
+  - search
+  - mkdocstrings
+  - etc
+  - jupyterlite:
+      enabled: true
+      notebook_patterns:
+        - "**/*.ipynb"
+      pip_urls:
+        - "https://pypi.org/simple"
+```

mkdocs_jupyterlite-0.1.0/README.md

@@ -0,0 +1,39 @@
+# mkdocs-jupyterlite
+
+A MkDocs plugin that enables embedding interactive jupyterlite notebooks in your docs.
+
+Say you have a notebook `example.ipynb` in your awesome project, and you want
+users to be able to play around with it.
+In the past, you could use a tool like [Binder](https://mybinder.org/) to achieve this.
+But, that requires a full docker environment and a remote server.
+By using [JupyterLite](https://jupyterlite.readthedocs.io/),
+you can run Jupyter notebooks directly in the browser without any server-side dependencies.
+
+However, to use jupyterlite, you have to manually install jupyterlite and
+then run a build step to package your notebooks, other files, and python
+dependencies into a single static site.
+
+This plugin automates that process for you.
+
+## Installation
+
+1. Install the plugin
+
+```bash
+pip install mkdocs-jupyterlite
+```
+
+2. Configure in your `mkdocs.yml` file
+
+```yaml
+plugins:
+  - search
+  - mkdocstrings
+  - etc
+  - jupyterlite:
+      enabled: true
+      notebook_patterns:
+        - "**/*.ipynb"
+      pip_urls:
+        - "https://pypi.org/simple"
+```

mkdocs_jupyterlite-0.1.0/docs/index.md

@@ -0,0 +1,39 @@
+# mkdocs-jupyterlite
+
+A MkDocs plugin that enables embedding interactive jupyterlite notebooks in your docs.
+
+Say you have a notebook `example.ipynb` in your awesome project, and you want
+users to be able to play around with it.
+In the past, you could use a tool like [Binder](https://mybinder.org/) to achieve this.
+But, that requires a full docker environment and a remote server.
+By using [JupyterLite](https://jupyterlite.readthedocs.io/),
+you can run Jupyter notebooks directly in the browser without any server-side dependencies.
+
+However, to use jupyterlite, you have to manually install jupyterlite and
+then run a build step to package your notebooks, other files, and python
+dependencies into a single static site.
+
+This plugin automates that process for you.
+
+## Installation
+
+### Step 1: Install the `mkdocs-jupyterlite` package
+
+```bash
+pip install mkdocs-jupyterlite
+```
+
+### Step 2: Configure your `mkdocs.yml` file
+
+```yaml
+plugins:
+  - search
+  - mkdocstrings
+  - etc
+  - jupyterlite:
+      enabled: true
+      notebook_patterns:
+        - "**/*.ipynb"
+      pip_urls:
+        - "https://pypi.org/simple"
+```

mkdocs_jupyterlite-0.1.0/docs/notebook.ipynb

@@ -0,0 +1,57 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "e311f1e4",
+   "metadata": {},
+   "source": [
+    "# Notebook 1"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2de0b9fe",
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "x = 1"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a6b80ff4",
+   "metadata": {},
+   "source": [
+    "## Heading 2"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "28f91d4a",
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "import ipywidgets\n",
+    "\n",
+    "ipywidgets.IntSlider()"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

mkdocs_jupyterlite-0.1.0/mkdocs.yml

@@ -0,0 +1,14 @@
+site_name: mkdocs-jupyterlite
+site_url: https://nickcrews.github.io/mkdocs-jupyterlite/
+repo_url: https://github.com/nickcrews/mkdocs-jupyterlite/
+
+nav:
+  - Home: index.md
+  - Notebook 1: notebook.ipynb
+
+plugins:
+  - jupyterlite:
+      enabled: true
+      notebook_patterns:
+        - '*.ipynb'
+      pip_urls: []

mkdocs_jupyterlite-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "mkdocs-jupyterlite"
+version = "0.1.0"
+description = "Embed interactive JupyterLite notebooks in your MkDocs site."
+readme = "README.md"
+authors = [
+    { name = "Nick Crews", email = "nicholas.b.crews@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "jupyterlab-server>=2.27.3",
+    "jupyterlite-core>=0.6.4",
+    "jupyterlite-pyodide-kernel>=0.6.1",
+    "mkdocs>=1.6.1",
+]
+
+[project.urls]
+Documentation = "https://github.com/NickCrews/mkdocs-jupyterlite#readme"
+Homepage = "https://github.com/NickCrews/mkdocs-jupyterlite"
+Source = "https://github.com/NickCrews/mkdocs-jupyterlite"
+Tracker = "https://github.com/NickCrews/mkdocs-jupyterlite/issues"
+
+[project.entry-points."mkdocs.plugins"]
+jupyterlite = "mkdocs_jupyterlite:JupyterlitePlugin"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.1",
+]
+lint = [
+    "ruff>=0.12.8",
+]

mkdocs_jupyterlite-0.1.0/src/mkdocs_jupyterlite/__init__.py

@@ -0,0 +1,13 @@
+import importlib.metadata
+import warnings
+
+from mkdocs_jupyterlite._plugin import JupyterlitePlugin as JupyterlitePlugin
+from mkdocs_jupyterlite._plugin import (
+    JupyterlitePluginConfig as JupyterlitePluginConfig,
+)
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError as e:
+    warnings.warn(f"Could not determine version of {__name__}\n{e!s}", stacklevel=2)
+    __version__ = "unknown"

mkdocs_jupyterlite-0.1.0/src/mkdocs_jupyterlite/_build.py

@@ -0,0 +1,74 @@
+import json
+import logging
+import shutil
+import subprocess
+import tempfile
+from collections.abc import Iterable
+from pathlib import Path
+
+log = logging.getLogger("mkdocs.plugins.jupyterlite")
+
+
+def build_site(
+    *,
+    notebooks: Iterable[Path],
+    pip_urls: Iterable[str],
+    output_dir: Path,
+) -> None:
+    shutil.rmtree(output_dir, ignore_errors=True)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory() as working_dir_str:
+        working_dir = Path(working_dir_str)
+        write_jupyter_lite_config(
+            out_path=working_dir / "jupyter_lite_config.json",
+            pip_urls=pip_urls,
+        )
+        contents_args = []
+        for notebook in notebooks:
+            contents_args.extend(["--contents", str(notebook)])
+        cmd = [
+            "jupyter",
+            "lite",
+            "build",
+            # *(["--debug"] if debug else []),
+            "--debug",
+            *contents_args,
+            "--no-libarchive",
+            "--apps",
+            "notebooks",
+            "--no-unused-shared-packages",
+            "--output-dir",
+            str(output_dir),
+        ]
+        log.info("[jupyterlite] running build command: " + " ".join(cmd))
+        try:
+            result = subprocess.run(
+                cmd,
+                # capture_output=True,
+                text=True,
+                cwd=working_dir,
+                check=True,
+            )
+            if result.stdout:
+                log.debug("[jupyterlite] build output:\n" + result.stdout)
+        except subprocess.CalledProcessError as e:
+            log.error("[jupyterlite] build failed")
+            if e.stdout:
+                log.debug("[jupyterlite] build stdout:\n" + e.stdout)
+            if e.stderr:
+                log.error("[jupyterlite] build stderr:\n" + e.stderr)
+            raise
+        assert output_dir.exists(), "Output directory was not created"
+
+
+def write_jupyter_lite_config(
+    *,
+    out_path: Path,
+    pip_urls: Iterable[str],
+) -> None:
+    config = {
+        "JupyterLiteAddon": {
+            "piplite_urls": list(pip_urls),
+        }
+    }
+    out_path.write_text(json.dumps(config, indent=2))

mkdocs_jupyterlite-0.1.0/src/mkdocs_jupyterlite/_plugin.py

@@ -0,0 +1,162 @@
+import fnmatch
+import logging
+import shutil
+import tempfile
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any, Literal
+
+import markdown
+import nbformat
+from mkdocs.config.base import Config as BaseConfig
+from mkdocs.config.config_options import Type as OptionType
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.plugins import BasePlugin
+from mkdocs.structure.files import File, Files
+from mkdocs.structure.pages import Page
+from mkdocs.structure.toc import TableOfContents, get_toc
+from nbconvert import MarkdownExporter
+
+from mkdocs_jupyterlite import _build
+
+log = logging.getLogger("mkdocs.plugins.jupyterlite")
+
+
+class NotebookFile(File):
+    """
+    Wraps a regular File object to make .ipynb files appear as valid documentation files.
+    """
+
+    def __init__(self, file: File) -> None:
+        self._file = file
+
+    def __getattr__(self, name: str) -> Any:
+        return self._file.__getattribute__(name)
+
+    def is_documentation_page(self) -> Literal[True]:
+        return True
+
+
+class JupyterlitePluginConfig(BaseConfig):
+    enabled = OptionType(bool, default=True)
+    notebook_patterns = OptionType(list, default=[])
+    pip_urls = OptionType(list, default=[])
+
+
+class JupyterlitePlugin(BasePlugin[JupyterlitePluginConfig]):
+    def __init__(self):
+        super().__init__()
+        if isinstance(self.config, dict):
+            plugin_config = JupyterlitePluginConfig()
+            plugin_config.load_dict(self.config)
+            self.config = plugin_config
+        self._jupyterlite_build_dir = tempfile.TemporaryDirectory()
+
+    def _cleanup(self) -> None:
+        log.info(
+            "[jupyterlite] cleaning up temporary build directory: "
+            + str(self._jupyterlite_build_dir.name)
+        )
+        self._jupyterlite_build_dir.cleanup()
+
+    def on_files(self, files: Files, config: MkDocsConfig) -> Files:
+        outfiles = []
+        notebook_paths = []
+        for file in files:
+            if is_notebook(
+                relative_path=file.src_uri,
+                notebook_patterns=self.config.notebook_patterns,
+            ):
+                log.info("[jupyterlite] including notebook: " + str(file.abs_src_path))
+                outfiles.append(NotebookFile(file))
+                notebook_paths.append(file.abs_src_path)
+            else:
+                log.debug("[jupyterlite] ignoring file: " + str(file.abs_src_path))
+                outfiles.append(file)
+        notebooks = [Path(config.docs_dir) / p for p in notebook_paths]
+        _build.build_site(
+            notebooks=notebooks,
+            pip_urls=self.config.pip_urls,
+            output_dir=Path(self._jupyterlite_build_dir.name),
+        )
+        return Files(outfiles)
+
+    def on_pre_page(
+        self, page: Page, /, *, config: MkDocsConfig, files: Files
+    ) -> Page | None:
+        if not isinstance(page.file, NotebookFile):
+            return page
+        log.info("[jupyterlite] on_pre_page " + str(page.file.src_uri))
+
+        def new_render(self: Page, config: MkDocsConfig, files: Files) -> None:
+            body = f"""
+            <iframe src="{config.site_url}jupyterlite/notebooks/index.html?path={page.file.src_uri}"
+                width="100%"
+                height="800px"
+                frameborder="1">
+            </iframe>
+            """
+            self.content = body
+            toc, title_in_notebook = get_nb_toc_and_title(page.file.abs_src_path)
+            self.toc = toc
+            if title_in_notebook:
+                self.title = title_in_notebook
+
+        # replace render with new_render for this object only
+        page.render = new_render.__get__(page, Page)
+        return page
+
+    def on_post_build(self, config: MkDocsConfig) -> None:
+        shutil.copytree(
+            self._jupyterlite_build_dir.name,
+            Path(config.site_dir) / "jupyterlite",
+            dirs_exist_ok=True,
+        )
+        self._cleanup()
+
+    def on_build_error(self, *, error: Exception) -> None:
+        self._cleanup()
+
+
+def is_notebook(*, relative_path: str | Path, notebook_patterns: Iterable[str]) -> bool:
+    for pattern in notebook_patterns:
+        if fnmatch.fnmatch(relative_path, pattern):
+            return True
+    return False
+
+
+# Hooks for development
+def on_startup(command: str, dirty: bool) -> None:
+    log.info("[jupyterlite][development] plugin started.")
+
+
+def on_page_markdown(markdown: str, page: Any, config: MkDocsConfig, files: Any) -> str:
+    log.info("[jupyterlite][development] plugin started.")
+    plugin = JupyterlitePlugin()
+    return plugin.on_page_markdown(markdown, page=page, config=config, files=files)
+
+
+def on_post_page(output: str, page: Page, config: MkDocsConfig) -> str:
+    log.info("[jupyterlite][development] plugin started.")
+    plugin = JupyterlitePlugin()
+    return plugin.on_post_page(output, page=page, config=config)
+
+
+def on_files(files: Files, config: MkDocsConfig) -> Files:
+    log.info("[jupyterlite][development] plugin started.")
+    plugin = JupyterlitePlugin()
+    return plugin.on_files(files, config)
+
+
+def get_nb_toc_and_title(path: str | Path) -> tuple[TableOfContents, str | None]:
+    """Returns a TOC and title (the first heading, if present) for the Notebook."""
+    notebook = nbformat.reads(Path(path).read_text(), as_version=4)
+    (markdown_source, _resources) = MarkdownExporter().from_notebook_node(notebook)
+    md = markdown.Markdown(extensions=["toc"])
+    md.convert(markdown_source)
+    toc = get_toc(md.toc_tokens)
+    title = None
+    for token in md.toc_tokens:
+        if token["level"] == 1 and title is None:
+            title = token["name"]
+    return toc, title