Add .ipynb notebooks to document sympy & related routines (#139)

  - nmodl-odes-overview contains a higher level overview of the approach to solving ODEs in nmodl
  - nmodl-kinetic-schemes describes the Kinetic scheme maths & KineticBlockVisitor
  - nmodl-sympy-solver describes the SympySolver visitor (incomplete)
  - nmodl-linear-solver describes the sympy linear solver routines (incomplete)
  - nmodl-nonlinear-solver describes the Newton solver & related sympy routines (incomplete)
  - nmodl-sympy-conductance describes the SymyConductance visitor

Also,

  - add README.md to notebooks folder, with links to interactive colab jupyter session
    - the links won't work yet as repo is still private & nmodl is not installed,
    - but once github repo is public & nmodl is on pypi, we can add `! pip install nmodl` to top of notebook and they should work
  - exposed inline/folding/renaming/kinetic visitors via pybind for use in these notebooks
  - added `nb-format` cmake target to run nbconvert and clean_ipynb on notebooks
  - updated yaml.load to avoid warning message: https://github.com/yaml/pyyaml/wiki/PyYAML-yaml.load(input)-Deprecation
  - use yaml.safe_load instead of yaml.load

CMakeLists.txt

@@ -45,6 +45,23 @@ set(NMODL_ClangFormat_DEPENDENCIES pyastgen parser-gen
     FORCE)
 add_subdirectory(cmake/hpc-coding-conventions/cpp)
 
+# =============================================================================
+# Format & execute ipynb notebooks in place (pip install nbconvert clean-ipynb)
+# =============================================================================
+add_custom_target(nb-format
+                  jupyter
+                  nbconvert
+                  --to
+                  notebook
+                  --execute
+                  --inplace
+                  --ExecutePreprocessor.timeout=360
+                  "${CMAKE_SOURCE_DIR}/docs/notebooks/*.ipynb"
+                  &&
+                  clean_ipynb
+                  --keep-output
+                  "${CMAKE_SOURCE_DIR}/docs/notebooks/*.ipynb")
+
 # =============================================================================
 # Include cmake modules
 # =============================================================================

docs/index.rst

@@ -22,9 +22,13 @@ Welcome to nmodl's documentation!
    :maxdepth: 3
    :caption: Jupyter Notebooks:
 
-   notebooks/nmodl-python-sympy-examples
-   notebooks/nmodl-python-tutorial
-   notebooks/kinetic-schemes
+   notebooks/nmodl-python-tutorial.ipynb
+   notebooks/nmodl-odes-overview.ipynb
+   notebooks/nmodl-kinetic-schemes.ipynb
+   notebooks/nmodl-sympy-solver.ipynb
+   notebooks/nmodl-linear-solver.ipynb
+   notebooks/nmodl-nonlinear-solver.ipynb
+   notebooks/nmodl-sympy-conductance.ipynb
 
 .. toctree::
    :maxdepth: 2

docs/notebooks/README.md

@@ -0,0 +1,14 @@
+## NMODL jupyter notebooks
+
+To get started with the NMODL python interface:
+  - [nmodl-python-tutorial.ipynb](nmodl-python-tutorial.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/BlueBrain/nmodl/blob/add_sympy_documentation/docs/notebooks/nmodl-python-tutorial.ipynb)
+
+For an overview of ODEs in NODL:
+  - [nmodl-odes-overview.ipynb](nmodl-odes-overview.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/BlueBrain/nmodl/blob/add_sympy_documentation/docs/notebooks/nmodl-odes-overview.ipynb)
+
+For more specific implementation details:
+  - [nmodl-kinetic-schemes.ipynb](nmodl-kinetic-schemes.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/BlueBrain/nmodl/blob/add_sympy_documentation/docs/notebooks/nmodl-kinetic-schemes.ipynb)
+  - [nmodl-sympy-solver.ipynb](nmodl-sympy-solver.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/BlueBrain/nmodl/blob/add_sympy_documentation/docs/notebooks/nmodl-sympy-solver.ipynb)
+  - [nmodl-linear-solver.ipynb](nmodl-linear-solver.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/BlueBrain/nmodl/blob/add_sympy_documentation/docs/notebooks/nmodl-linear-solver.ipynb)
+  - [nmodl-nonlinear-solver.ipynb](nmodl-nonlinear-solver.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/BlueBrain/nmodl/blob/add_sympy_documentation/docs/notebooks/nmodl-nonlinear-solver.ipynb)
+  - [nmodl-sympy-conductance.ipynb](nmodl-sympy-conductance.ipynb) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/BlueBrain/nmodl/blob/add_sympy_documentation/docs/notebooks/nmodl-sympy-conductance.ipynb)