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¶
Install cookiecutter:
$ pip install cookiecutter
We’ll also need poetry so [install that too](https://python-poetry.org/docs/#installation):
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/fedejaure/cookiecutter-modern-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, 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. This is so that Travis CI and pyup.io can find it when we get to Step 5.
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
mypackage $ git init .
mypackage $ git add .
mypackage $ git commit -m "Initial skeleton."
mypackage $ git remote add origin git@github.com:myusername/mypackage.git
mypackage $ git push -u origin master
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.
Install the new project’s local development requirements inside a virtual environment using poetry:
$ poetry install
$ poetry run inv install_hooks
Step 5: 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.
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.
Now your documentation will get rebuilt when you make documentation changes to your package.
Step 6: 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 7: 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.
When you are ready, release your package the standard Python way.
See PyPI Help for more information about submitting a package.
