From fdb05e2b362ef4a779ef3f2153af2494463d4385 Mon Sep 17 00:00:00 2001 From: e-belfer Date: Thu, 30 Jan 2025 10:43:58 -0500 Subject: [PATCH] Add git github and API keys --- learners/setup.md | 188 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 159 insertions(+), 29 deletions(-) diff --git a/learners/setup.md b/learners/setup.md index 4244a31..9fc1a11 100644 --- a/learners/setup.md +++ b/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. - -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. + -### 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 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 Windows Logo Key\+R, entering `cmd`, and hitting +Return. 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'} + +::::::::::::::::::::::::: + +