Tutorial#

Note

This tutorial is adapted for pyfar from the Forked repo!

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#

Install your cookiecutter into a virtualenv. Assuming you have Anaconda or Miniconda installed, this is how you set up and activate your virtual environment:

conda create --name mypackage python
conda activate mypackage

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

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-pypackage repo:

cookiecutter https://github.com/pyfar/cookiecutter-pypackage.git

You’ll be asked to enter a bunch of values to set the package up. If you don’t know what to enter, have a look to Prompts or stick with the defaults.

Step 3: Create a GitHub Repo#

Go to your GitHub account and create a new repo named mypackage, where mypackage matches the [project_slug] from your answers to running cookiecutter.

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
git init .
git add .
git commit -m "Initial skeleton."
git branch -M main
git remote add origin git@github.com:myusername/mypackage.git
git push -u origin main

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

You’ll need a ssh key to push the repo. You can Generate a key or Add an existing one.

Step 4: Install Dev Requirements#

You should still be in the folder containing the pyproject.toml file.

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

pip install -e ".[dev]"

Step 5: Set Up Circle Ci#

CircleCI is a continuous integration tool used to prevent integration problems. Every commit to a branch will trigger automated testing for the package.

Login using your Github credentials. It may take a few minutes for CircleCi to load up a list of all your GitHub repos. They in the Projects environment.

Add the public repo to your CircleCI account by clicking Set Up Project next to the mypackage repo. Choose the .circleci/config.yml file and the main branch and click Set Up Project. No need to do further settings.

You can now push to your GitHub repo and CircleCI will automatically run the tests. You can see the status of your tests in the CircleCI dashboard and on Github.

Step 6: Set Up Read the Docs#

Read the Docs hosts documentation for the open source community. Think of it as Continuous Documentation.

Log into your account at Read the Docs. If you don’t have one, create one and log into it via your GitHub account. Connect your GitHub account to your Read the Docs account. Click on the Add project button. You should find your project mypackage repo listed. Use the Continue button to import the project via using the automatic configuration. It is already setup in your Github repository with the .readthedocs.yaml file.

Step 8: 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.

First we need to setup the automatic deployment of the package to PyPI cia CircleCI. It is already configured in the .circleci/config.yml file.

All we need to do is adding the token to the CircleCI project. See PyPI Help for more information about it.

When you are ready, release your package as described in the pyfar deploying guidelines.

Having problems?#

Go to our Issues page and create a new Issue. Be sure to give as much information as possible.