Skip to content

Quickstart

Requirements

  • A *NIX system (e.g. Linux/macOS) - Windows might work, but we don't support it
  • Conda

  • Cookiecutter Python package >= 1.4.0:

    pip install cookiecutter  # might be pip3 on your machine

  • direnv - Automatically loads environment variables and environments 

    brew install direnv  # Mac
apt-get install -y direnv  # Ubuntu Linux
    Add eval "$(direnv hook $SHELL)" at the end of your ~/.${SHELL}rc file.

  • Optional: AWS CLI installed and configured
    • Install - pip install awscli

    • Configure

      Fetch (or generate) security credentials from the AWS dashboard by clicking "Create access key".

      Run aws configure, inputting the access key ID and secret access key ID you just generated when prompted.

      In addition you should set the default region name to eu-west-2 and the default output format to json.

      AWS provide a more detailed guide here.

Create

Ensure you have installed the requirements and then run cookiecutter https://github.com/nestauk/ds-cookiecutter -c <VERSION TAG>.

If you do not specify a version tag then cookiecutter will use the latest commit on the master branch. Unless specifying a version you have used before, check the release notes to see what changed since you last created a project!

Currently, only the latest release's docs are available online. You can serve docs for a specific release on your machine by checking out that release and running pip install -r requirements.txt && cd docs && mkdocs serve and then navigating to localhost:8000 in your browser.

This opens a series of prompts to configure your new project (values in square brackets denote defaults).

What do the prompts mean?
  • project_name: Type the name of your project here
  • repo_name: Type the name of your repository here
    • The default is a processed version of project_name that is compatible with python package names
  • author_name: The author of the project
  • description: A short description of your project
  • openness: Whether the project is "public" (default) or "private"
    • If "public" then an MIT license will be generated; otherwise the license will be a copyright placeholder

Configure

When you change directory to your created project folder, you will see that you are in a git repository and the generated cookiecutter has committed itself to the 0_setup_cookiecutter branch.

Run make install to:

  • Create a conda environment (with a name corresponding to the repo_name prompt) and install the project package in editable mode and its dependencies
  • Configure and install Git pre-commit hooks

Look in .recipes/GithubCreation.md for a quick method of creating and configuring a Github repo for this project.

Now you're setup, you may wish to adapt the cookiecutter to fill your specific needs, e.g. by looking at other components in .recipes/ (see FAQ).

Collaborating on an existing project

  • Clone the repository and cd into the repository.
  • Run make install to configure the development environment (see above section)
  • Check the project's README for any additional configuration needed (e.g. putting API keys in .env)
    • Ideally that projects maintainer will have extended the Makefile to do additional configuration automatically
  • Follow the author's documentation, or make them write some if they haven't already!