Tutorial

Note

Did you find any of these instructions confusing? Edit this file and submit a pull request with your improvements!

To start with, you will need a GitHub account and an account on PyPI. Create these before you get started on this tutorial. If you are new to Git and GitHub, you should probably spend a few minutes on some of the tutorials at the top of the page at GitHub Help.

Step 1: Install Cookiecutter

First, you need to create and activate a virtualenv for the package project. Use your favorite method, or create a virtualenv for your new package like this:

virtualenv ~/.virtualenvs/mypackage

Here, mypackage is the name of the package that you’ll create.

Activate your environment:

source bin/activate

On Windows, activate it like this. You may find that using a Command Prompt window works better than gitbash.

> \path\to\env\Scripts\activate

Install cookiecutter:

pip install cookiecutter

Step 2: Generate Your Package

Now it’s time to generate your Python package.

Use cookiecutter, pointing it at the cookiecutter-pyopensci repo:

cookiecutter https://github.com/pyOpenSci/cookiecutter-pyopensci.git

You’ll be asked to enter a bunch of values to set the package up. If you don’t know what to enter, stick with the defaults. Here’s a list of the options, and a brief description:

  • full_name: Enter package creator’s full name.
  • email: Enter email address.
  • github_username: Package creator’s github username.
  • project_name: Choose a short and descriptive name for your package.
  • project_slug: A shorthand name for your project, using “_” instead of spaces and avoiding “-“.
  • project_short_description: Short (one sentence) description of your package and what it does.
  • pypi_username: Username for deploying to PyPI. If you don’t have one, just leave as default for now. This is not important for now.
  • version: Version number for your package. If unsure, leave as default.
  • use_pypi_deployment_with_travis: Travis CI can automatically deploy your project to PyPI when you update to a new version number. If you are unsure, leave as “n”. This can be changed later.
  • add_pyup_badge: PyUp.io is a service that helps keep your package compatitible with updates to its dependencies.
  • open_source_license: Select an open source software license. For more guidance, see the license section of the pyOpenSci guidebook. If you would like to use a license not on this list, just choose one and replace the LICENSE file with the license of your choosing.

The result will be a newly-created repository in a new folder called [project_slug]. Next, we’ll upload this repository to GitHub.

Step 3: Create a GitHub Repo

Next we need to create an online repository on GitHub where you can push your newly-created local repository.

Go to your GitHub account and create a new repo named mypackage, where mypackage matches the [project_slug] from your answers to running cookiecutter. This is so that Travis CI and pyup.io can find it when we get to Step 5.

Note

If your virtualenv folder is within your project folder, be sure to add the virtualenv folder name to your .gitignore file.

You will find one folder named after the [project_slug]. Move into this folder, and then setup git to use your GitHub repo and upload the code:

cd mypackage
# Create an empty repository
git init .
# Add and commit all the files in this repository
git add .
git commit -m "Initial skeleton."
# Add our GitHub.com repository as a "remote" and push to it
git remote add origin git@github.com:myusername/mypackage.git
git push -u origin master

Where myusername and mypackage are adjusted for your username and package name.

You’ll need an ssh key to push the repo to GitHub. You can Generate a key or Add an existing key that allows your to do so.

Step 4: Install Development Requirements

Next you’ll need to install the packages needed to develop your repository. Any repository should come packaged with a list of the packages needed to work with it (both as a developer and as a user). When you ran the cookiecutter command, a sample requirements file was created, called requirements_dev.txt.

You should still be in the root folder of your repository. It should contain a requirements_dev.txt file.

Your virtualenv should still be activated. If it isn’t, activate it now. Install the new project’s local development requirements:

pip install -r requirements_dev.txt

This will install all of the packages specified in requirements_dev.txt into your environment.

Step 5: Set Up Travis CI

Travis CI org [*] is a continuous integration tool used to prevent integration problems. Every commit to the master branch will trigger automated builds of the application, and it is common to run a series of tests along with each build to ensure the code still behaves the way we’d expect.

Login using your Github credentials. It may take a few minutes for Travis CI to load up a list of all your GitHub repos. They will be listed with boxes to the left of the repo name, where the boxes have an X in them, meaning it is not connected to Travis CI.

Add the public repo to your Travis CI account by clicking the X to switch it “on” in the box next to the mypackage repo. Do not try to follow the other instructions, that will be taken care of next.

If you chose to turn on automatic PyPI deployment via Travis CI, see Travis/PyPI Setup for more information.

[*]For private projects go to Travis CI com

Step 6: Set Up ReadTheDocs

ReadTheDocs hosts documentation for the open source community. Think of it as Continuous Documentation. When you make changes to a branch, ReadTheDocs will automatically re-build your documentation so they reflect the latest changes.

Log into your account at ReadTheDocs . If you don’t have one, create one and log into it.

If you are not at your dashboard, choose the pull-down next to your username in the upper right, and select “My Projects”. Choose the button to Import the repository and follow the directions.

In your GitHub repo, select Settings > Webhooks & Services, turn on the ReadTheDocs service hook.

Now your documentation will get rebuilt when you make documentation changes to your package.

Step 7 (optional): Set Up pyup.io

pyup.io is a service that helps you to keep your requirements files up to date. It sends you automated pull requests whenever there’s a new release for one of your dependencies.

To use it, create a new account at pyup.io or log into your existing account.

Click on the green Add Repo button in the top left corner and select the repo you created in Step 3. A popup will ask you whether you want to pin your dependencies. Click on Pin to add the repo.

Once your repo is set up correctly, the pyup.io badge will show your current update status.

Step 8 (optional): Release on PyPI

The Python Package Index or PyPI is the official third-party software repository for the Python programming language. Python developers intend it to be a comprehensive catalog of all open source Python packages.

Note

If you are submitting your package for pyOpenSci peer-review, we ask that you wait to release your package on PyPI. This makes it easier to implement changes during the review process. If you are already on PyPI, that’s no problem of course!

When you are ready, see PyPI Help for more information about submitting a package.

Here’s a release checklist you can use: PyPI Release Checklist:

If you turned on automatic deployment to PyPI via Travis, see Travis/PyPI Setup for more info.

Having problems?

Visit our Troubleshooting page for help. If that doesn’t help, go to our Issues page and create a new Issue. Be sure to give as much information as possible.