Use a notebook for quickstart (#568)

Our Quickstart documentation is now an executable document (.ipynb notebook) Detailed changelog: * Changed pre-commit config in preparation for jupyter notebooks * Added jupyterlab3 as dev requirement for docs * Basic rewrite of quickstart as a notebook * Added nc files generated by notebooks to .gitignore * Added nbsphinx and other notebook doc dependencies aswell as configs * Added headings for quicker navigation * Added some jupyter helpers to make the output prettier And made flake8 for notebooks ignore 'E402 module level import not at top of file' * Added binder config * Replaced 'IPython.display.Code' with custom 'print_yaml_file' function The problem with 'Code' was, while it was properly syntax highlighted in the Html docs, it doesn't work in jupyterlab (see: issue 11747 in ipython/ipython) and the workaround is longer than the markdown wrapping in 'print_yaml_file'. Also, the colormap used by 'pygments' does not adjust or work well with the dark theme. * Added pandoc to doc related CI tasks, so the docs will actually build * Added tests for the notebooks, that way errors can be easier spotted * Adjusted notebook to API changes * Added pre-commit hook to remove empty notebook cells * Use tox-direct when no seperate env is needed E.g. docs, docs-links, docs-notebooks, pre-commit since those should all be runnable in the local devenv. The main reason to use tox-direct is that building the docs fails with image path resolving errors for the notebooks. * Added Trigger-Binder-build workflow and binder badge That way users don't need to wait for the binder image to build, since it gets built each push to main * Added ast-check and isort to notebook pre-commit hooks * Removed usage warning * Replaced my feature branch deprendency of tox-direct with new release on PyPi
glotaran · Feb 28, 2021 · bea2e73 · bea2e73
1 parent 19cb8c6
commit bea2e73
Show file tree

Hide file tree

Showing 17 changed files with 666 additions and 282 deletions.
diff --git a/.github/workflows/CI_CD_actions.yml b/.github/workflows/CI_CD_actions.yml
@@ -17,12 +17,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
+      - name: Setup conda
+        uses: s-weigand/setup-conda@v1
+        with:
+          conda-channels: conda-forge
+          activate-conda: false
       - name: Set up Python 3.8
         uses: actions/setup-python@v2
         with:
           python-version: 3.8
       - name: Install dependencies
         run: |
+          conda install -y pandoc
           python -m pip install -U pip wheel
           pip install .
           python -m pip install -U -r requirements_dev.txt
@@ -36,12 +42,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
+      - name: Setup conda
+        uses: s-weigand/setup-conda@v1
+        with:
+          conda-channels: conda-forge
+          activate-conda: false
       - name: Set up Python 3.8
         uses: actions/setup-python@v2
         with:
           python-version: 3.8
       - name: Install dependencies
         run: |
+          conda install -y pandoc
           python -m pip install -U pip wheel
           pip install .
           python -m pip install -U -r requirements_dev.txt
@@ -55,6 +67,25 @@ jobs:
         if: ${{ always() }}
         run: cat linkcheck-output.txt | grep -E "(\(line.*\)|writing output)"
 
+  docs-notebooks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.8
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip wheel
+          pip install .
+          python -m pip install -U -r requirements_dev.txt
+      - name: Show installed packages
+        run: pip freeze
+      - name: Build docs
+        run: |
+          py.test -vv --nbval docs/source/notebooks
+
   test:
     runs-on: ${{ matrix.os }}
     needs: pre-commit
@@ -88,7 +119,7 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
-    needs: [test, docs]
+    needs: [test, docs, docs-notebooks]
     steps:
       - uses: actions/checkout@v2
       - name: Set up Python 3.8

diff --git a/.github/workflows/trigger-binder.yml b/.github/workflows/trigger-binder.yml
@@ -0,0 +1,15 @@
+name: "Trigger-Binder-build"
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  trigger-binder-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: s-weigand/trigger-mybinder-build@v1
+        with:
+          target-repo: glotaran/pyglotaran
+          target-state: main
diff --git a/.gitignore b/.gitignore
@@ -7,8 +7,6 @@ tests/resources/PE2017
 # Dask
 dask-worker-space/
 
-# Notebook
-*.ipynb
 
 # TIMP data
 *.RData
@@ -95,6 +93,9 @@ docs/source/user_documentation/api/*
 # doc figures
 docs/source/images/plot
 
+# Datafiles created by notebooks
+docs/**/*.nc
+
 # PyBuilder
 target/
 

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,4 +1,5 @@
 repos:
+  # Formatters
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v3.4.0
     hooks:
@@ -40,6 +41,37 @@ repos:
     hooks:
       - id: setup-cfg-fmt
 
+  # Notebook tools
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.3.9
+    hooks:
+      - id: nbstripout
+
+  - repo: https://github.com/nbQA-dev/nbQA
+    rev: 0.5.7
+    hooks:
+      - id: nbqa-black
+        additional_dependencies: [black==20.8b1]
+        args: [--nbqa-mutate]
+      - id: nbqa-pyupgrade
+        additional_dependencies: [pyupgrade==2.9.0]
+        args: [--nbqa-mutate, --py38-plus]
+      - id: nbqa-flake8
+      - id: nbqa-check-ast
+      - id: nbqa-isort
+        additional_dependencies: [isort==5.7.0]
+        args: [--nbqa-mutate]
+
+  - repo: local
+    hooks:
+      - id: nbstripout-empty
+        name: Strip empty notebook cells
+        language: system
+        entry: python docs/strip_empty_notebook_cells.py
+        types: [jupyter]
+
+  # Linters
+
   # - repo: https://github.com/PyCQA/pydocstyle
   #   rev: 5.1.1
   #   hooks:
@@ -52,6 +84,7 @@ repos:
   #   rev: v1.5.5
   #   hooks:
   #     - id: darglint
+
   - repo: https://github.com/econchick/interrogate
     rev: 1.3.2
     hooks:
@@ -85,5 +118,5 @@ repos:
     rev: v2.0.0
     hooks:
       - id: codespell
-        files: ".py|.rst"
+        files: ".py|.rst|.ipynb"
         args: [-L doas]
diff --git a/README.md b/README.md
@@ -6,10 +6,11 @@ pyGloTarAn is a Python library for Global and Target Analysis
 [![Conda Version](https://img.shields.io/conda/vn/conda-forge/pyglotaran.svg)](https://anaconda.org/conda-forge/pyglotaran)
 ![Tests](https://github.com/glotaran/pyglotaran/workflows/Tests/badge.svg)
 [![Documentation Status](https://readthedocs.org/projects/pyglotaran/badge/?version=latest)](https://pyglotaran.readthedocs.io/en/latest/?badge=latest)
+[![Binder](https://static.mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/glotaran/pyglotaran.git/main?urlpath=lab%2Ftree%2Fdocs%2Fsource%2Fnotebooks)
 [![Coverage Status](https://codecov.io/gh/glotaran/pyglotaran/branch/master/graph/badge.svg)](https://codecov.io/gh/glotaran/pyglotaran)
 [![Total alerts](https://img.shields.io/lgtm/alerts/g/glotaran/pyglotaran.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/glotaran/pyglotaran/alerts/)
 
-**Warning**: This is an *early access* release, please refer to the [usage notice](#usage-notice)   down below prior to committing to use pyglotaran to avoid surprises down the line.
+**Warning**: This is an _early access_ release, please refer to the [usage notice](#usage-notice) down below prior to committing to use pyglotaran to avoid surprises down the line.
 
 ## Installation
 
@@ -44,7 +45,7 @@ cd pyglotaran
 pip install .
 ```
 
-_To enforce the installation within a Python3 environment on systems where Python2 is the default, instead of the last command use `pip3 install .`.
+\_To enforce the installation within a Python3 environment on systems where Python2 is the default, instead of the last command use `pip3 install .`.
 
 _Note for Anaconda Users: Please make sure to update your distribution prior to install since some packages managed by Anaconda cannot be updated by `pip`._
 
@@ -62,7 +63,7 @@ The examples used in this validation process can be obtained from the [pyglotara
 
 The pyglotaran package derives its name from the glotaran software package (now called [glotaran-legacy](https://github.com/glotaran/glotaran-legacy)), first released in 2011 and described in a highly-cited publication in the Journal of Statistical Software, under the title [Glotaran: A Java-Based Graphical User Interface for the R Package TIMP](https://www.jstatsoft.org/article/view/v049i03) ([DOI: 10.18637/jss.v049.i03](http://dx.doi.org/10.18637/jss.v049.i03)).
 
-The [pyglotaran](https://github.com/glotaran/pyglotaran) software can be considered the spiritual successor of the  [glotaran-legacy](https://github.com/glotaran/glotaran-legacy) software and has the backing of many of its original creators.
+The [pyglotaran](https://github.com/glotaran/pyglotaran) software can be considered the spiritual successor of the [glotaran-legacy](https://github.com/glotaran/glotaran-legacy) software and has the backing of many of its original creators.
 
 ## The future of global and target analysis
 

diff --git a/binder/environment.yml b/binder/environment.yml
@@ -0,0 +1,14 @@
+channels:
+  - conda-forge
+dependencies:
+  # Jupyter
+  - jupyterlab=3
+  - jupyter-offlinenotebook=0.2
+  # Python Kernel
+  - ipykernel>5.1
+  - python=3.8
+  # update outdated repo2docker version
+  - pip
+  - pip:
+      - -r ../requirements_dev.txt
+      - ..
diff --git a/binder/postBuild b/binder/postBuild
@@ -0,0 +1,5 @@
+#!/bin/bash
+set -ex
+
+# run matplotlib once to generate the font cache
+python -c "import matplotlib as mpl; mpl.use('Agg'); import pylab as plt; fig, ax = plt.subplots(); fig.savefig('test.png')"
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -49,9 +49,9 @@
     "sphinx.ext.imgmath",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
+    "nbsphinx",
+    "sphinx_last_updated_by_git",
     "numpydoc",
-    "IPython.sphinxext.ipython_directive",
-    "IPython.sphinxext.ipython_console_highlighting",
     "sphinx_copybutton",
 ]
 
@@ -98,6 +98,74 @@
 pygments_style = "sphinx"
 
 
+# -- nbsphinx config ------------------------------------------------------
+
+
+# This is processed by Jinja2 and inserted before each notebook
+nbsphinx_prolog = r"""
+{% set docname = 'docs/source/' + env.doc2path(env.docname, base=None)| replace('\\', '/') %}
+{% set binder_url = 'lab/tree/docs/source/' + env.doc2path(env.docname, base=None)|urlencode %}
+
+.. raw:: html
+    {{ binder_url }}
+
+    <div class="admonition note">
+      This page was generated from
+      <a class="reference external" href="https://github.com/glotaran/pyglotaran/blob/{{ env.config.release|e }}/{{ docname|e }}">{{ docname|e }}</a>.
+      Interactive online version:
+    <span style="white-space: nowrap;">
+        <a
+            href="https://mybinder.org/v2/gh/glotaran/pyglotaran/{{ env.config.release|e }}?urlpath={{ binder_url|e }}">
+            <img alt="Binder badge" src="https://mybinder.org/badge_logo.svg" style="vertical-align:text-bottom">
+        </a>
+    </span>
+
+      <script>
+        if (document.location.host) {
+          $(document.currentScript).replaceWith(
+            '<a class="reference external" ' +
+            'href="https://nbviewer.jupyter.org/url' +
+            (window.location.protocol == 'https:' ? 's/' : '/') +
+            window.location.host +
+            window.location.pathname.slice(0, -4) +
+            'ipynb">View in <em>nbviewer</em></a>.'
+          );
+        }
+      </script>
+    </div>
+
+
+.. raw:: latex
+
+
+    \nbsphinxstartnotebook{\scriptsize\noindent\strut
+    \textcolor{gray}{The following section was generated from
+    \sphinxcode{\sphinxupquote{\strut {{ docname | escape_latex }}}} \dotfill}}
+"""
+
+nbsphinx_execute_arguments = [
+    "--InlineBackend.figure_formats={'svg', 'pdf'}",
+    "--InlineBackend.rc figure.dpi=96",
+]
+
+
+# -- Config for sphinx_last_updated_by_git --------------------------------
+
+# Get version information and date from Git
+try:
+    from subprocess import check_output
+
+    release = check_output(["git", "describe", "--tags", "--always"])
+    release = release.decode().strip()
+    today = check_output(["git", "show", "-s", "--format=%ad", "--date=short"])
+    today = today.decode().strip()
+except Exception:
+    release = "<unknown>"
+    today = "<unknown date>"
+
+git_untracked_check_dependencies = False
+
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -12,7 +12,7 @@ Welcome to pyglotaran's documentation!
 
    introduction
    installation
-   quickstart
+   notebooks/quickstart
    history
    authors
 

diff --git a/docs/source/notebooks/model.yaml b/docs/source/notebooks/model.yaml
@@ -0,0 +1,29 @@
+type: kinetic-spectrum
+
+initial_concentration:
+ input:
+   compartments: [s1, s2, s3]
+   parameters: [input.1, input.0, input.0]
+
+k_matrix:
+ k1:
+   matrix:
+     (s2, s1): kinetic.1
+     (s3, s2): kinetic.2
+     (s3, s3): kinetic.3
+
+megacomplex:
+ m1:
+   k_matrix: [k1]
+
+irf:
+ irf1:
+   type: gaussian
+   center: irf.center
+   width: irf.width
+
+dataset:
+ dataset1:
+   initial_concentration: input
+   megacomplex: [m1]
+   irf: irf1
diff --git a/docs/source/notebooks/parameters.yaml b/docs/source/notebooks/parameters.yaml
@@ -0,0 +1,13 @@
+input:
+ - ['1', 1, {'vary': False, 'non-negative': False}]
+ - ['0', 0, {'vary': False, 'non-negative': False}]
+
+kinetic: [
+    0.5,
+    0.3,
+    0.1,
+]
+
+irf:
+ - ['center', 0.3]
+ - ['width', 0.1]