Merge pull request #3 from aeisenbarth/github-actions

GitHub actions

.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: Continuous integration
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - "v*"
+  pull_request:
+    branches: [main]
+
+jobs:
+  tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Setup PDM
+        uses: pdm-project/setup-pdm@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: true
+      - name: Install dependencies
+        run: pdm sync
+      - name: Run pytest
+        run: pdm test
+
+  linting:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Setup PDM
+        uses: pdm-project/setup-pdm@v3
+        with:
+          python-version: "3.12"
+          cache: true
+      - name: Install dependencies
+        run: pdm sync
+      - name: Run linting
+        run: pdm lint
+
+  publish:
+    name: Publish to PyPI
+    if: github.ref_type == 'tag'
+    needs: [tests, linting]
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Setup PDM
+        uses: pdm-project/setup-pdm@v3
+      - name: Build
+        run: pdm build
+      - name: Publish
+        run: pdm publish --no-build

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Build docs
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  build-docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup PDM
+        uses: pdm-project/setup-pdm@v3
+        with:
+          python-version: "3.12"
+          cache: true
+      - name: Install dependencies
+        run: pdm sync
+      - name: Build docs
+        run: pdm docs
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload docs build directory
+          path: 'docs/_build/'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.pre-commit-config.yaml

@@ -9,6 +9,7 @@ repos:
       - id: check-merge-conflict
       - id: end-of-file-fixer
       - id: trailing-whitespace
+        exclude: tests/test_myst_nb/.*\.xml
   - repo: https://github.com/python/black
     rev: 22.3.0
     hooks:
@@ -60,3 +61,11 @@ repos:
       # Run the formatter.
       - id: ruff-format
         types_or: [python, pyi, jupyter]
+  - repo: https://github.com/jumanjihouse/pre-commit-hook-yamlfmt
+    rev: 0.2.3
+    hooks:
+      - id: yamlfmt
+        # TODO: Once supported, change --preserve-quotes to enforce double quotes, see
+        # https://github.com/jumanjihouse/pre-commit-hook-yamlfmt/issues/53
+        args: ["--mapping", "2", "--sequence", "4", "--offset", "2", "--width", "100", "--preserve-quotes",
+          "--implicit_start", "--implicit_end"]

README.md

@@ -5,14 +5,15 @@ A MIME-type plugin for rendering JSON output from Jupyter notebooks to HTML
 ______________________________________________________________________
 
 Outputs from Jupyter notebook code cells usually contain representations in one or multiple MIME
-types (image, text, ...). IPython provides multiple built-in output types, but not all of them
+types (image, text…). IPython provides multiple built-in output types, but not all of them
 have a representation for HTML, and fall back to a stringified version of the Python object.
 
 This is the case for the `application/json` type:
 
 It is nicely rendered in Jupyter because Jupyter includes a
 [JSON renderer](https://github.com/jupyterlab/jupyterlab/tree/7909745d075aceb0cf1099ad53a3174e92b575ae/packages/json-extension),
-but MyST-NB can only use IPython's built-ins which display as `<IPython.core.display.JSON object>`.
+but [MyST-NB](https://myst-nb.readthedocs.io) can only use IPython's built-ins which display as
+`<IPython.core.display.JSON object>`.
 
 ## Jupyter Lab
 

docs/examples.ipynb

@@ -44,6 +44,8 @@
     "\n",
     "- `application/json`'s data is the original JSON, and it is left up to renderers how to represent it.\n",
     "\n",
+    "## Comparison\n",
+    "\n",
     "Jupyter Lab renders the following:\n",
     "\n",
     "![Screenshot of json_dict in Jupyter](./images/example1-jupyter.png)\n",
@@ -52,11 +54,17 @@
     "\n",
     "![Screenshot of json_dict in HTML by MyST-NB](./images/example1-myst-nb.png)\n",
     "\n",
-    "With `myst-nb-json`, you should get an interactive rendering similar to Jupyter Lab:\n",
+    "With `myst-nb-json`, you will get an interactive rendering that looks similar to Jupyter Lab:\n",
     "\n",
     "![Screenshot of json_dict in HTML with myst-nb-json](./images/example1-myst-nb-json.png)"
    ]
   },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": "## MyST-NB-JSON",
+   "id": "c2e1a4f04d4045f1"
+  },
   {
    "cell_type": "code",
    "id": "23be0ec2f8ceb03a",
@@ -74,6 +82,8 @@
    "id": "cde3f57f5dd64638",
    "metadata": {},
    "source": [
+    "## Expanded\n",
+    "\n",
     "With the `expanded` parameter, you can control how much to show by default:"
    ]
   },
@@ -92,6 +102,8 @@
    "id": "32536237d491e70f",
    "metadata": {},
    "source": [
+    "## Root\n",
+    "\n",
     "With the `root` parameter, you can control the display name:"
    ]
   },
@@ -109,7 +121,11 @@
    "cell_type": "markdown",
    "id": "ed652ffb9714f6ae",
    "metadata": {},
-   "source": "This is also nice for **Pydantic** models! By default, they are rendered as plain text:"
+   "source": [
+    "## Pydantic\n",
+    "\n",
+    "This is also nice for **Pydantic** models! By default, they are rendered as plain text:"
+   ]
   },
   {
    "cell_type": "code",

docs/index.md

@@ -19,10 +19,13 @@ This is the case for the `application/json` type:
 
 It is nicely rendered in Jupyter because Jupyter includes a
 [JSON renderer](https://github.com/jupyterlab/jupyterlab/tree/7909745d075aceb0cf1099ad53a3174e92b575ae/packages/json-extension),
-but MyST-NB can only use IPython's built-ins which display as `<IPython.core.display.JSON object>`.
+but [MyST-NB](https://myst-nb.readthedocs.io) can only use IPython's built-ins which display as
+`<IPython.core.display.JSON object>`.
 
 ## Installation
 
+Make sure `Sphinx` and `myst-nb` are installed, this package is meant to be used with them.
+
 Install the Python package:
 
 ```shell

pyproject.toml

@@ -37,6 +37,7 @@ docs = [
     "docutils>=0.21.2",
     "ipython>=8.12.0",
     "myst-nb>=1.0.0",
+    "pydantic>=2.0",
     "Sphinx>=7.2.6",
     "sphinx-book-theme>=1.1.3",
 ]
@@ -48,7 +49,9 @@ test = [
     "selenium~=4.22",
     "Sphinx[test]>=7.2.6", # For test dependencies like defusedxml
 ]
-type-hints = ["types-docutils"]
+type-hints = [
+    "types-docutils>=0.21.0.20240423",
+]
 
 [project.entry-points."myst_nb.mime_renderers"]
 application_json = "myst_nb_json:JsonMimeRenderPlugin"