Skip to content

Commit

Permalink
Add documentation about Make on Windows (#355)
Browse files Browse the repository at this point in the history
* Fix typo

* Add instructions for Make on Windows

* Fix typo

* Copy edits

* Add note about help

* Consistent code formatting

---------

Co-authored-by: Jay Qi <jayqi@users.noreply.github.com>
  • Loading branch information
jayqi and jayqi committed Apr 7, 2024
1 parent 644bae7 commit 39a6cad
Showing 1 changed file with 46 additions and 5 deletions.
51 changes: 46 additions & 5 deletions docs/docs/using-the-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,29 @@ If you use GitHub and have the [gh cli tool](https://cli.github.com/) you can ea
gh repo create
```

You'll be asked a series of questions to set up the repository on GitHub. Once you're done you'll be able to push the changes in your local repository to GitHub.
You'll be asked a series of questions to set up the repository on GitHub. Once you're done you'll be able to push the changes in your local repository to GitHub.

## Create a Python virutal environment
## Make as a task runner

[GNU Make](https://www.gnu.org/software/make/) is a tool that is typically pre-installed on Linux and macOS systems, and we use it as a "task runner" for CCDS projects. This means that when we have a series of shell commands we might want to run, such setting up a virtual environment or syncing the data to cloud storage, we set them up as recipes in the `Makefile`. To use a recipe, simply call

```bash
make RECIPE_NAME
```

where `RECIPE_NAME` is the same of a recipe like `requirements` or `sync_data_up`. Projects created by CCDS include a `Makefile` with several recipes we've predefined. You'll see them referenced in the sections below. To see a list of all available commands, just call

```bash
make
```

on its own.

!!! note "Using Windows?"

If you are using Windows, you may need to install Make. See the ["Installing Make on Windows"](#installing-make-on-windows) section below.

## Create a Python virtual environment

We often use Python for our data science projects. We use a virtual environment to manage the packages we use in our project. This is a way to keep the packages we use in our project separate from the packages we use in other projects. This is especially important when we are working on multiple projects at the same time.

Expand Down Expand Up @@ -63,7 +83,7 @@ git checkout -b initial-exploration

## Open a notebook

!!! note
!!! note

The following assumes you're using a Jupyter notebook, but while the specific commands for another notebook tool may look a little bit different, the process guidance still applies.

Expand All @@ -80,7 +100,7 @@ Now you're ready to do some analysis! Make sure that your project-specific envir
- `3` - Modeling - training machine learning models
- `4` - Publication - Notebooks that get turned directly into reports
- `pjb` - Your initials; this is helpful for knowing who created the notebook and prevents collisions from people working in the same notebook.
- `data-source-1` - A description of what the notebook covers
- `data-source-1` - A description of what the notebook covers

Now that you have your notebook going, start your analysis!

Expand Down Expand Up @@ -133,4 +153,25 @@ Now you'll be able to [create a Pull Request in GitHub](https://docs.github.com/

## Changing the `Makefile`

There's no magic in the Makefile. We often add project-specific commands or update the existing ones over the course of a project. For example, we've added scripts to generate reports with pandoc, build and serve documentation, publish static sites from assets, package code for distribution, and more.
There's no magic in the `Makefile`. We often add project-specific commands or update the existing ones over the course of a project. For example, we've added scripts to generate reports with pandoc, build and serve documentation, publish static sites from assets, package code for distribution, and more.

## Installing Make on Windows

Unfortunately, GNU Make is not typically pre-installed on Windows. Here are a few different options for getting Make:

- **Use a package manager.** You will need to install the package manager first if you don't already have it.
- [chocolatey](https://community.chocolatey.org/) ([entry for Make](https://community.chocolatey.org/packages/make))
```bash
choco install make
```
- [winget](https://winget.run/) ([entry for Make](https://winget.run/pkg/GnuWin32/Make))
```bash
winget install -e --id GnuWin32.Make
```
- [scoop](https://scoop.sh/) ([entry for Make](https://scoop.sh/#/apps?q=make&id=c43ff861c0f1713336e5304d85334a29ffb86317))
```bash
scoop install main/make
```
- **Windows Subsystem for Linux**. WSL is a full, non-virtualized Linux environment inside Windows. You can use it to run all of your data science workflows on Ubuntu, and it will have Make included. See instructions for installing WSL [here](https://learn.microsoft.com/en-us/windows/wsl/install).
- **Cygwin**. A Unix-like development environment that includes Make. See instructions about installing Cygwin [here](https://www.cygwin.com/install.html).
- **MinGW**. A GNU development environment that runs on Windows and includes Make. See information about installing MinGW [here](https://www.mingw-w64.org/downloads/).

0 comments on commit 39a6cad

Please sign in to comment.