{ "cells": [ { "cell_type": "markdown", "metadata": { "lines_to_next_cell": 2 }, "source": [ "# Initial setup for instructors\n", "\n", "If you aren't familiar with how jupytext works, it would be good \n", "to spend some time at https://jupytext.readthedocs.io/en/latest/?badge=latest\n", "\n", "The notes below show how to bootstrap a repository with notebooks only committed\n", "as python files. That means that the first time through, we need to convert and\n", "execute the ipynb versions. Subsequently, jupyter will handle this through\n", "the modified jupyter_notebook_config.py described below.\n", "\n", "## installation\n", "\n", "1. Install miniconda if you don't have it -- note that our environment\n", " will be 100% conda-forge, so you don't want to use a large existing\n", " anaconda installation to create the e213 environment.\n", "\n", "2. clone the repo:\n", "\n", "```\n", "git clone https://github.com/eldadHaber/ComputationalGeoCourse\n", "cd ComputationalGeoCourse\n", "```\n", "\n", "3. cd to the `course_utils` folder and create and activate the e213 environment\n", "\n", "```\n", "cd course_utils\n", "conda env create -f e213.yml\n", "conda activate e213\n", "```\n", "\n", "4. Make sure you have a jupyter config folder\n", "\n", "```\n", "jupyter notebook --generate-config\n", "```\n", "\n", "This should put a `jupyter_notebook_config.py` file in your `~/.jupyter` folder\n", "\n", "5. Replace the config with the one in conda_utils\n", "\n", "```\n", "cp conda_utils/jupyter_notebook_config.py ~/.jupyter/.\n", "```\n", "\n", "## Building the notebooks\n", "\n", "We need to track three different flavors of notebook:\n", "\n", "a) Student versions\n", "b) Notebooks with solutions\n", "c) Documentation notebooks for website\n", "\n", "At the moment there are two sets, the student notebooks are in\n", "`ComputationalGeoCourse/notebooks` and the documentation notebooks\n", "are in `ComputationalGeoCourse/docs/docs_notebooks`\n", "\n", "To build from scratch, we need to convert the py files to ipynb files.\n", "\n", "To do this:\n", "\n", "1. `cd ComputationalGeoCourse`\n", "2. `python scripts/find_notebooks.py notebooks notebook_filelist.json --initial`\n", "\n", "This should create an ipynb file for every py file and a new json\n", "file calle `notebook_filelist.json`. We need to execute\n", "these, at this point we can suppress all errors:\n", "\n", "`python scripts/jup_build.py exec-noerrors-nb notebook_filelist.json`\n", "\n", "Repeat this for the docs notebooks:\n", "\n", "```\n", "python scripts/find_notebooks.py docs/doc_notebooks notebook_docs_filelist.json --initial\n", "python scripts/jup_build.py exec-noerrors-nb notebook_docs_filelist.json\n", "```\n", "\n", "## Making the course website\n", "\n", "The notebooks (ipynb) and any restructured text (rst) and markdown (md) files are assembled\n", "into a website using [nbsphinx](https://nbsphinx.readthedocs.io/en/0.5.0/). To build and\n", "deploy with github-pages:\n", "\n", "1. `cd ComputationalGeoCourse/docs`\n", "2. `./build_website.sh`\n", "\n", "\n", "and push to github\n", "\n", "\n", "1. `cd ComputationalGeoCourse/docs`\n", "2. `./push_pages.sh`\n", "\n", "\n", "## Push the student notebooks to their download repo\n", "\n", "We have a separate repo to maintain the notebooks and libraries that the students will\n", "download: https://github.com/phaustin/e213_students\n", "\n", "This repository is a mirror of everything that is in our [students folder](https://github.com/eldadHaber/ComputationalGeoCourse/tree/pha/students). My workflow for deploying\n", "to this folder:\n", "\n", "1. add a no-passphrase public key to the [e213_students](https://github.com/phaustin/e213_students) repository (mine is named new_pha_git)\n", "\n", "1. I put the following entry into my .ssh/config:\n", "\n", " Host phaustin\n", " HostName github.com\n", " User git\n", " IdentityFile ~/.ssh/new_pha_git\n", " IdentitiesOnly yes\n", " \n", "1. Add the following remote to the main [e213](https://github.com/eldadHaber/ComputationalGeoCourse) repository\n", "\n", "```\n", "git add remote students phaustin:phaustin/e213_students\n", "```\n", "\n", "1. Now you can use ghp-import to push the students folder to that remote using [push_students.sh](https://github.com/eldadHaber/ComputationalGeoCourse/tree/pha/scripts/push_students.sh)\n", "\n", "```\n", "scripts/push_students.sh\n", "```\n", "\n", "Note that I've removed the master branch from the repo and made \"downloads\" the default branch\n", "so we don't get confused between this and our master branch version of the students folder.\n", "\n", "**Important point -- you can commit new notebooks to the student folder as part of an e213 branch, but push_students.sh makes a separate commit of every file in the folder and completely overwrites the remote\n", "branch for every push. So treat everything on the remote branch as ephemeral.**\n", "\n", "# Student installs\n", "\n", "**If you already have conda or anaconda installed, skip to `Git install` below**\n", "\n", "\n", "\n", "## For MacOS new installs\n", "\n", "\n", "1. Download miniconda from https://docs.conda.io/en/latest/miniconda.html -- choose the `Miniconda3 MacOSX 64-bit pkg` file from the menu and run it, agreeing to the licences and accepting all defaults. You should install for \"just me\"\n", "\n", "1. To test your installation, open a fresh terminal window and at the prompt type `which conda`. You should see something resembling the following output, with your username instead of `phil`:\n", "\n", "```\n", "% which conda\n", "/Users/phil/opt/miniconda3/bin/conda\n", "```\n", "\n", "## For Windows new installs\n", "\n", "1. Download miniconda from https://docs.conda.io/en/latest/miniconda.html -- choose the `Miniconda3 Windows 64-bit`. download from the menu and run it, agreeing to the licences and accepting all defaults.\n", "\n", "The installer should suggest installing in a path that looks like:\n", "\n", "```\n", "C:\\Users\\phil\\Miniconda3\n", "```\n", "\n", "2. Once the install completes hit the windows key and start typing `anaconda`. You should see a shortcut that looks like:\n", "\n", "```\n", "Anaconda Powershell Prompt\n", "(Miniconda3)\n", "```\n", "\n", "**Note that Windows comes with two different terminals `cmd` (old) and `powershell` (new). Always select the powershell version of the anaconda terminal**\n", "\n", "3. Select the short cut. If the install was successful you should see something like:\n", "\n", "```\n", "(base) (Miniconda3):Users/phil>\n", "```\n", "with your username substituted for phil.\n", "\n", "## Git install\n", "\n", "Inside your powershell or MacOs terminal, install git using conda:\n", "\n", "```\n", "conda install git\n", "```\n", "\n", "## Setting up the course repository\n", "\n", "In the terminal, change directories to your home directory (called `~` for short) and make a new directory\n", "called `repos` to hold the course notebook repository. Change into `repos` and clone the course:\n", "\n", "```\n", "cd ~\n", "mkdir repos\n", "cd repos\n", "git clone https://github.com/phaustin/e213_students.git\n", "```\n", "\n", "## Creating the course environment\n", "\n", "In the terminal, execute the following commands:\n", "\n", "```\n", "cd e213_students/utils\n", "conda env create -f e213.yml\n", "conda activate e213\n", "```\n", "\n", "## Opening the notebook folder\n", "\n", "```\n", "cd ~/repos/e213_students/e213_notebooks\n", "jupyter notebook\n", "```\n" ] } ], "metadata": { "jupytext": { "cell_metadata_filter": "all", "formats": "ipynb,py:percent", "notebook_metadata_filter": "all,-language_info,-toc,-latex_envs" }, "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" } }, "nbformat": 4, "nbformat_minor": 2 }