docs: add notebook button for Deepnote (#400)

* ci: build documentation on Python 3.8 * ci: update pip constraints and pre-commit config * docs: add notebook button for Deepnote * docs: simplify install cells * fix: limit Sphinx on Python <=3.7 Causes conflicts with importlib-metadata https://github.com/ComPWA/tensorwaves/actions/runs/1704199025 Co-authored-by: GitHub <noreply@github.com>
ComPWA · Jan 16, 2022 · 94a7317 · 94a7317
1 parent 730b89a
commit 94a7317
Show file tree

Hide file tree

Showing 17 changed files with 244 additions and 158 deletions.
diff --git a/.constraints/py3.6.txt b/.constraints/py3.6.txt
@@ -182,9 +182,9 @@ smmap==5.0.0
 sniffio==1.2.0
 snowballstemmer==2.2.0
 soupsieve==2.3.1
-sphinx==4.3.2
+sphinx==4.3.2 ; python_version < "3.8.0"
 sphinx-autobuild==2021.3.14
-sphinx-book-theme==0.1.10
+sphinx-book-theme==0.2.0
 sphinx-copybutton==0.4.0
 sphinx-panels==0.6.0
 sphinx-thebe==0.0.10

diff --git a/.constraints/py3.7.txt b/.constraints/py3.7.txt
@@ -188,9 +188,9 @@ smmap==5.0.0
 sniffio==1.2.0
 snowballstemmer==2.2.0
 soupsieve==2.3.1
-sphinx==4.3.2
+sphinx==4.3.2 ; python_version < "3.8.0"
 sphinx-autobuild==2021.3.14
-sphinx-book-theme==0.1.10
+sphinx-book-theme==0.2.0
 sphinx-copybutton==0.4.0
 sphinx-panels==0.6.0
 sphinx-thebe==0.0.10

diff --git a/.constraints/py3.8.txt b/.constraints/py3.8.txt
@@ -188,9 +188,9 @@ smmap==5.0.0
 sniffio==1.2.0
 snowballstemmer==2.2.0
 soupsieve==2.3.1
-sphinx==4.3.2
+sphinx==4.4.0
 sphinx-autobuild==2021.3.14
-sphinx-book-theme==0.1.10
+sphinx-book-theme==0.2.0
 sphinx-copybutton==0.4.0
 sphinx-panels==0.6.0
 sphinx-thebe==0.0.10

diff --git a/.constraints/py3.9.txt b/.constraints/py3.9.txt
@@ -187,9 +187,9 @@ smmap==5.0.0
 sniffio==1.2.0
 snowballstemmer==2.2.0
 soupsieve==2.3.1
-sphinx==4.3.2
+sphinx==4.4.0
 sphinx-autobuild==2021.3.14
-sphinx-book-theme==0.1.10
+sphinx-book-theme==0.2.0
 sphinx-copybutton==0.4.0
 sphinx-panels==0.6.0
 sphinx-thebe==0.0.10

diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-docs.yml
@@ -16,14 +16,14 @@ jobs:
     runs-on: ubuntu-20.04
     steps:
       - uses: actions/checkout@v2
-      - name: Set up Python 3.7
+      - name: Set up Python 3.8
         uses: actions/setup-python@v2
         with:
-          python-version: "3.7"
+          python-version: "3.8"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -c .constraints/py3.7.txt .[doc]
+          pip install -c .constraints/py3.8.txt .[doc]
           sudo apt-get -y install graphviz pandoc
       - name: Build documentation and run notebooks
         working-directory: docs

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -44,15 +44,16 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/ComPWA/repo-maintenance
-    rev: 0.0.98
+    rev: 0.0.99
     hooks:
       - id: check-dev-files
         args:
           - --pin-requirements
       - id: fix-first-nbcell
         args:
-          - --colab
-          - --replace
+          - --add-install-cell
+          - --additional-packages=IPython
+          - --extras-require=doc,viz
       - id: fix-nbformat-version
       - id: format-setup-cfg
 
@@ -125,6 +126,7 @@ repos:
             metadata.toc-showmarkdowntxt
             metadata.toc-showtags
             metadata.varInspector
+
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v2.5.1
     hooks:

diff --git a/docs/amplitude-analysis.ipynb b/docs/amplitude-analysis.ipynb
@@ -19,25 +19,34 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
-    "%config Completer.use_jedi = False\n",
     "%config InlineBackend.figure_formats = ['svg']\n",
     "import os\n",
     "\n",
-    "STATIC_WEB_PAGE = {\"EXECUTE_NB\", \"READTHEDOCS\"}.intersection(os.environ)\n",
-    "\n",
-    "# Install on Google Colab\n",
-    "import subprocess\n",
-    "import sys\n",
-    "\n",
-    "from IPython import get_ipython\n",
-    "\n",
-    "install_packages = \"google.colab\" in str(get_ipython())\n",
-    "if install_packages:\n",
-    "    for package in [\"tensorwaves[doc]\", \"graphviz\"]:\n",
-    "        subprocess.check_call(\n",
-    "            [sys.executable, \"-m\", \"pip\", \"install\", package]\n",
-    "        )"
+    "STATIC_WEB_PAGE = {\"EXECUTE_NB\", \"READTHEDOCS\"}.intersection(os.environ)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "hideCode": true,
+    "hideOutput": true,
+    "hidePrompt": true,
+    "jupyter": {
+     "source_hidden": true
+    },
+    "slideshow": {
+     "slide_type": "skip"
+    },
+    "tags": [
+     "remove-cell",
+     "skip-execution"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# WARNING: advised to install a specific version, e.g. tensorwaves==0.1.2\n",
+    "%pip install -q tensorwaves[doc,viz] IPython"
    ]
   },
   {

diff --git a/docs/amplitude-analysis/analytic-continuation.ipynb b/docs/amplitude-analysis/analytic-continuation.ipynb
@@ -19,25 +19,34 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
-    "%config Completer.use_jedi = False\n",
     "%config InlineBackend.figure_formats = ['svg']\n",
     "import os\n",
     "\n",
-    "STATIC_WEB_PAGE = {\"EXECUTE_NB\", \"READTHEDOCS\"}.intersection(os.environ)\n",
-    "\n",
-    "# Install on Google Colab\n",
-    "import subprocess\n",
-    "import sys\n",
-    "\n",
-    "from IPython import get_ipython\n",
-    "\n",
-    "install_packages = \"google.colab\" in str(get_ipython())\n",
-    "if install_packages:\n",
-    "    for package in [\"tensorwaves[doc]\", \"graphviz\"]:\n",
-    "        subprocess.check_call(\n",
-    "            [sys.executable, \"-m\", \"pip\", \"install\", package]\n",
-    "        )"
+    "STATIC_WEB_PAGE = {\"EXECUTE_NB\", \"READTHEDOCS\"}.intersection(os.environ)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "hideCode": true,
+    "hideOutput": true,
+    "hidePrompt": true,
+    "jupyter": {
+     "source_hidden": true
+    },
+    "slideshow": {
+     "slide_type": "skip"
+    },
+    "tags": [
+     "remove-cell",
+     "skip-execution"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# WARNING: advised to install a specific version, e.g. tensorwaves==0.1.2\n",
+    "%pip install -q tensorwaves[doc,viz] IPython"
    ]
   },
   {

diff --git a/docs/conf.py b/docs/conf.py
@@ -152,6 +152,7 @@ def fetch_logo(url: str, output_path: str) -> None:
     "launch_buttons": {
         "binderhub_url": "https://mybinder.org",
         "colab_url": "https://colab.research.google.com",
+        "deepnote_url": "https://deepnote.com",
         "notebook_interface": "jupyterlab",
         "thebe": True,
         "thebelab": True,

diff --git a/docs/usage.ipynb b/docs/usage.ipynb
@@ -19,25 +19,34 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
-    "%config Completer.use_jedi = False\n",
     "%config InlineBackend.figure_formats = ['svg']\n",
     "import os\n",
     "\n",
-    "STATIC_WEB_PAGE = {\"EXECUTE_NB\", \"READTHEDOCS\"}.intersection(os.environ)\n",
-    "\n",
-    "# Install on Google Colab\n",
-    "import subprocess\n",
-    "import sys\n",
-    "\n",
-    "from IPython import get_ipython\n",
-    "\n",
-    "install_packages = \"google.colab\" in str(get_ipython())\n",
-    "if install_packages:\n",
-    "    for package in [\"tensorwaves[doc]\", \"graphviz\"]:\n",
-    "        subprocess.check_call(\n",
-    "            [sys.executable, \"-m\", \"pip\", \"install\", package]\n",
-    "        )"
+    "STATIC_WEB_PAGE = {\"EXECUTE_NB\", \"READTHEDOCS\"}.intersection(os.environ)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "hideCode": true,
+    "hideOutput": true,
+    "hidePrompt": true,
+    "jupyter": {
+     "source_hidden": true
+    },
+    "slideshow": {
+     "slide_type": "skip"
+    },
+    "tags": [
+     "remove-cell",
+     "skip-execution"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# WARNING: advised to install a specific version, e.g. tensorwaves==0.1.2\n",
+    "%pip install -q tensorwaves[doc,viz] IPython"
    ]
   },
   {

diff --git a/docs/usage/basics.ipynb b/docs/usage/basics.ipynb
@@ -19,25 +19,34 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
-    "%config Completer.use_jedi = False\n",
     "%config InlineBackend.figure_formats = ['svg']\n",
     "import os\n",
     "\n",
-    "STATIC_WEB_PAGE = {\"EXECUTE_NB\", \"READTHEDOCS\"}.intersection(os.environ)\n",
-    "\n",
-    "# Install on Google Colab\n",
-    "import subprocess\n",
-    "import sys\n",
-    "\n",
-    "from IPython import get_ipython\n",
-    "\n",
-    "install_packages = \"google.colab\" in str(get_ipython())\n",
-    "if install_packages:\n",
-    "    for package in [\"tensorwaves[doc]\", \"graphviz\"]:\n",
-    "        subprocess.check_call(\n",
-    "            [sys.executable, \"-m\", \"pip\", \"install\", package]\n",
-    "        )"
+    "STATIC_WEB_PAGE = {\"EXECUTE_NB\", \"READTHEDOCS\"}.intersection(os.environ)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "hideCode": true,
+    "hideOutput": true,
+    "hidePrompt": true,
+    "jupyter": {
+     "source_hidden": true
+    },
+    "slideshow": {
+     "slide_type": "skip"
+    },
+    "tags": [
+     "remove-cell",
+     "skip-execution"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# WARNING: advised to install a specific version, e.g. tensorwaves==0.1.2\n",
+    "%pip install -q tensorwaves[doc,viz] IPython"
    ]
   },
   {

diff --git a/docs/usage/binned-fit.ipynb b/docs/usage/binned-fit.ipynb
@@ -19,25 +19,34 @@
    },
    "outputs": [],
    "source": [
-    "%%capture\n",
-    "%config Completer.use_jedi = False\n",
     "%config InlineBackend.figure_formats = ['svg']\n",
     "import os\n",
     "\n",
-    "STATIC_WEB_PAGE = {\"EXECUTE_NB\", \"READTHEDOCS\"}.intersection(os.environ)\n",
-    "\n",
-    "# Install on Google Colab\n",
-    "import subprocess\n",
-    "import sys\n",
-    "\n",
-    "from IPython import get_ipython\n",
-    "\n",
-    "install_packages = \"google.colab\" in str(get_ipython())\n",
-    "if install_packages:\n",
-    "    for package in [\"tensorwaves[doc]\", \"graphviz\"]:\n",
-    "        subprocess.check_call(\n",
-    "            [sys.executable, \"-m\", \"pip\", \"install\", package]\n",
-    "        )"
+    "STATIC_WEB_PAGE = {\"EXECUTE_NB\", \"READTHEDOCS\"}.intersection(os.environ)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "hideCode": true,
+    "hideOutput": true,
+    "hidePrompt": true,
+    "jupyter": {
+     "source_hidden": true
+    },
+    "slideshow": {
+     "slide_type": "skip"
+    },
+    "tags": [
+     "remove-cell",
+     "skip-execution"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# WARNING: advised to install a specific version, e.g. tensorwaves==0.1.2\n",
+    "%pip install -q tensorwaves[doc,viz] IPython"
    ]
   },
   {