Add git github and API keys

learners/setup.md

@@ -2,53 +2,183 @@
 title: Setup
 ---
 
-FIXME: Setup instructions live in this document. Please specify the tools and
-the data sets the Learner needs to have installed.
+## Overview
 
-## Data Sets
+This lesson is designed to be run on a personal computer.
+All of the software and data used in this lesson are freely available online,
+and instructions on how to obtain them are provided below.
 
-<!--
-FIXME: place any data you want learners to use in `episodes/data` and then use
-       a relative link ( [data zip file](data/lesson-data.zip) ) to provide a
-       link to it, replacing the example.com link.
--->
-Download the [data zip file](https://example.com/FIXME) and unzip it to your Desktop
+## Obtain lesson materials
 
-## Software Setup
+TODO: Do we want people to fork the entire repo or just download the data? If the first, that should come after GH setup.
+<!-- 1. Download [python-novice-inflammation-data.zip][zipfile1]
+  and [python-novice-inflammation-code.zip][zipfile2].
+2. Create a folder called `swc-python` on your Desktop.
+3. Move downloaded files to `swc-python`.
+4. Unzip the files.
 
-::::::::::::::::::::::::::::::::::::::: discussion
+You should see two folders called `data` and `code` in the `swc-python` directory on your
+Desktop. -->
 
-### Details
+## Accessing lesson data
 
-Setup for different systems can be presented in dropdown menus via a `spoiler`
-tag. They will join to this discussion block, so you can give a general overview
-of the software used in this lesson here and fill out the individual operating
-systems (and potentially add more, e.g. online setup) in the solutions blocks.
+### Create an API key for accessing the EIA API
+In episode 3 and 4, we'll be learning how to access the Application Programming Interface (API)
+for the Energy Information Administration (EIA). To register for an EIA API key:
 
-:::::::::::::::::::::::::::::::::::::::::::::::::::
+1. Go to the [EIA API website](https://www.eia.gov/opendata/).
+2. Click "Register" on the right-hand side and complete the form.
+3. Log in to the email address you provided - you should have received an email from the
+EIA with the subject line "EIA API Registration Key" that contains your API key.
 
-:::::::::::::::: spoiler
+### Create an API key for accessing the EPA API
+In episode 3 and 4, we'll also be exploring the Environmental Protection Agency's (EPA)
+Clean Air Markets API portal. To register for an EPA API key:
 
-### Windows
+1. Go to the [registration page](https://www.epa.gov/power-sector/cam-api-portal#/api-key-signup) and fill out the form.
+2. Log in to the email address you provided. You should have received an email from the EPA
+containing an API key for the Clean Air Markets API portal.
 
-Use PuTTY
+## Installing Git
 
-::::::::::::::::::::::::
+Since many Carpentries lessons rely on Git, please see
+[this section of the workshop template](https://carpentries.github.io/workshop-template/install_instructions/#git) for
+instructions on installing Git for various operating systems.
 
-:::::::::::::::: spoiler
+- [Git installation on Windows](https://carpentries.github.io/workshop-template/install_instructions/#git)
+- [Git installation on MacOS](https://carpentries.github.io/workshop-template/install_instructions/#git)
+- [Git installation on Linux](https://carpentries.github.io/workshop-template/install_instructions/#git)
 
-### MacOS
+## Create an account on GitHub
 
-Use Terminal.app
+You will need an account for [GitHub](https://github.com) to follow episodes *(TODO!)* in this lesson.
 
-::::::::::::::::::::::::
+1. Go to <https://github.com> and follow the "Sign up" link at the top-right of the window.
+2. Follow the instructions to create an account.
+3. Verify your email address with GitHub.
+4. Configure multifactor authentication (see below).
 
+Basic GitHub accounts are free. As you set up your account,p lease consider what personal
+information you'd like to reveal. For example, you may want to review these
+[instructions for keeping your email address private]("https://help.github.com/articles/keeping-your-email-address-private/") provided at GitHub.
 
-:::::::::::::::: spoiler
+### Multi-factor Authentication
 
-### Linux
+In 2023, GitHub introduced a requirement for 
+all accounts to have 
+[multi-factor authentication (2FA)](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication) 
+configured for extra security.
+Several options exist for setting up 2FA, which are summarised here:
 
-Use Terminal
+1. If you already use an authenticator app, 
+   like [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en&co=GENIE.Platform%3DiOS&oco=0) 
+   or [Duo Mobile](https://duo.com/product/multi-factor-authentication-mfa/duo-mobile-app) on your smartphone for example, 
+   [add GitHub to that app](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-mobile-app).
+2. If you have access to a smartphone but do not already use an authenticator app, install one and 
+   [add GitHub to the app](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-mobile-app).
+3. If you do not have access to a smartphone or do not want to install an authenticator app, you have two options:
+    1. [set up 2FA via text message](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-text-messages) 
+       ([list of countries where authentication by SMS is supported](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/countries-where-sms-authentication-is-supported)), or
+    2. [use a hardware security key](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-security-key) 
+       like [YubiKey](https://www.yubico.com/products/yubikey-5-overview/) 
+       or the [Google Titan key](https://store.google.com/us/product/titan_security_key?hl=en-US&pli=1).
 
-::::::::::::::::::::::::
+The GitHub documentation provides [more details about configuring 2FA](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication).
 
+## Launch Python interface - TODO!
+
+To start working with Python, we need to launch a program that will interpret and execute our
+Python commands. Below we list several options. If you don't have a preference, proceed with the
+top option in the list that is available on your machine. Otherwise, you may use any interface
+you like.
+
+## Option A: Jupyter Notebook
+
+A Jupyter Notebook provides a browser-based interface for working with Python.
+If you installed Anaconda, you can launch a notebook in two ways:
+
+::::::::::::::::: spoiler
+
+## Anaconda Navigator
+
+1. Launch Anaconda Navigator.
+  It might ask you if you'd like to send anonymized usage information to Anaconda developers:
+  ![](fig/anaconda-navigator-first-launch.png){alt='Anaconda Navigator first launch'}
+  Make your choice and click "Ok, and don't show again" button.
+2. Find the "Notebook" tab and click on the "Launch" button:
+  ![](fig/anaconda-navigator-notebook-launch.png){alt='Anaconda Navigator Notebook launch'}
+  Anaconda will open a new browser window or tab with a Notebook Dashboard showing you the
+  contents of your Home (or User) folder.
+3. Navigate to the `data` directory by clicking on the directory names leading to it:
+  `Desktop`, `swc-python`, then `data`:
+  ![](fig/jupyter-notebook-data-directory.png){alt='Anaconda Navigator Notebook directory'}
+4. Launch the notebook by clicking on the "New" button and then selecting "Python 3":
+  ![](fig/jupyter-notebook-launch-notebook.png){alt='Anaconda Navigator Notebook directory'}
+
+:::::::::::::::::::::::::
+
+
+::::::::::::::::: spoiler
+
+## Command line (Terminal)
+
+1\. Navigate to the `data` directory:
+
+::::::::::::::::: spoiler
+
+## Unix shell
+
+If you're using a Unix shell application, such as Terminal app in macOS, Console or Terminal
+in Linux, or [Git Bash][gitbash] on Windows, execute the following command:
+
+```bash
+cd ~/Desktop/swc-python/data
+```
+
+:::::::::::::::::::::::::
+
+::::::::::::::::: spoiler
+
+## Command Prompt (Windows)
+
+On Windows, you can use its native Command Prompt program.  The easiest way to start it up is
+pressing <kbd>Windows Logo Key</kbd>\+<kbd>R</kbd>, entering `cmd`, and hitting
+<kbd>Return</kbd>. In the Command Prompt, use the following command to navigate to
+the `data` folder:
+
+```source
+cd /D %userprofile%\Desktop\swc-python\data
+```
+
+:::::::::::::::::::::::::
+
+2\. Start Jupyter server
+
+::::::::::::::::: spoiler
+
+## Unix shell
+
+```bash
+jupyter notebook
+```
+
+:::::::::::::::::::::::::
+
+
+::::::::::::::::: spoiler
+
+## Command Prompt (Windows)
+
+```source
+python -m notebook
+```
+
+:::::::::::::::::::::::::
+
+3\. Launch the notebook by clicking on the "New" button on the right and selecting "Python 3"
+from the drop-down menu:
+![](fig/jupyter-notebook-launch-notebook2.png){alt='Anaconda Navigator Notebook directory'}
+
+:::::::::::::::::::::::::
+
+  <!-- vertical spacer -->