Merge pull request #67 from nismod/web_tutorials

Web version of tutorials

.environment.yml

@@ -12,7 +12,7 @@ dependencies:
   - matplotlib
   - nbstripout
   - networkx
-  - numpy
+  - numpy <2.0.0
   - openpyxl
   - pandera
   - pip
@@ -30,3 +30,4 @@ dependencies:
     - python-igraph
     - snkit
     - tqdm
+    - -e .

.gitignore

@@ -30,3 +30,4 @@ CMakeFiles/*
 
 # Docs
 docs/build
+.DS_Store

docs/source/conf.py

@@ -38,13 +38,16 @@ def setup(app):
     "sphinx.ext.autodoc",
     "sphinx.ext.coverage",
     "sphinx.ext.viewcode",
+    "nbsphinx",
+    "sphinx_gallery.load_style",
 ]
 templates_path = ["_templates"]
 exclude_patterns = []
 
 # The suffix(es) of source filenames.
 source_suffix = [".rst"]
 
+nbsphinx_execute="never"
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docs/source/index.rst

@@ -34,9 +34,11 @@ climate hazards on infrastructure networks.
     :alt: PyPI version
 
 
-## Installation
+Installation
+----------------
 
-Install using pip:
+Install using pip
+=================
 
     pip install nismod-snail
 
@@ -58,7 +60,12 @@ If all worked okay, you should be able to run python and import snail::
     NAME
         snail - snail - the spatial networks impact assessment library
 
-## Using the `snail` command
+
+
+
+
+Using the `snail` command
+-------------------------
 
 Once installed, you can use `snail` directly from the command line.
 
@@ -92,14 +99,18 @@ Where at a minimum, each CSV has a column `path` with the path to each file.
    :maxdepth: 2
    :caption: Contents:
 
-
 Contents
 --------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+
+   setup
+
+.. toctree::
+   :maxdepth: 1
 
-   Getting Started <getting_started>
+   Tutorials <tutorials>
 
 .. toctree::
    :maxdepth: 3

docs/source/setup.ipynb

@@ -0,0 +1,122 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Getting started\n",
+    "\n",
+    "The notebooks can be downloaded from:\n",
+    "notebook tutorials: https://github.com/nismod/snail/tree/master/tutorials.\n",
+    "\n",
+    "This note will cover the technical setup that allows to locally run the notebooks and reproduce the results. \n",
+    "It is recommended to use a micromamba environement and this section will be using it to setup a jupyter notebook or VScode workflows. \n",
+    "\n",
+    "### Setup\n",
+    "\n",
+    "The two cases considered are setup of a jupyter environment, or a VScode project to run the tutorials. \n",
+    "Once you have downloaded the repo or copied the tutorials notebooks into a folder, navigate to it via the terminal. Once inside, run the following: "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "vscode": {
+     "languageId": "shellscript"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "# with conda\n",
+    "conda env create -n snail_env \\\n",
+    "    python=3.8 geopandas shapely rasterio python-igraph\n",
+    "conda activate snail_env\n",
+    "pip install nismod-snail\n",
+    "\n",
+    "# with micromamba\n",
+    "\n",
+    "micromamba create -n snail-env \\ \n",
+    "    python=3.8 geopandas shapely rasterio python-igraph -c conda-forge\n",
+    "micromamba activate snail-env"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The previous step will setup a conda or micromamba virtual environment with some packages and activate it.\n",
+    "Next, install the *snail* package, it will bring with intself a bunch of dependencies to run the tutorials. \n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "vscode": {
+     "languageId": "shellscript"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "pip install nismod-snail"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Running the tutorials\n",
+    "\n",
+    "At this point, if you type `jupyter notebook` in the terminal and execute, a jupyter server will start and open a browser window with the repository containing the tutorials.\n",
+    "\n",
+    "#### Using VSCode\n",
+    "\n",
+    "If you are using VSCode, you might run into issues with micromamba as it does not recognise it by default, it will look for `venv` and `conda` virtual environments only. \n",
+    "Open VSCode from inside the tutorials folder and open the first tutorial.\n",
+    "<!-- In the searchbar that opens once you do this, you will  -->\n",
+    "Now back to the terminal, execute the following command: "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "vscode": {
+     "languageId": "shellscript"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "# on MAC\n",
+    "which python\n",
+    "\n",
+    "# # on Windows\n",
+    "# where python"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    " Now on the upper right corner of VSCode choose *Select Kernel*. When the options show up, go for *Select another kernel*.\n",
+    " In the searchbar, paste the output of the terminal command, it should be something like: `USERNAME/micromamba/envs/snail-env/bin/python`"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "After that, VSCode will connect to the virtual environment you created earlier and you will be all set up !"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/source/tutorials.rst

@@ -0,0 +1,8 @@
+
+Tutorials
+==========
+.. nbgallery::
+   tutorials/01-data-preparation-ghana
+   tutorials/02-assess-damage-and-disruption
+   tutorials/03-test-multiple-failures
+   tutorials/04-evaluate-adaptation-options