This repository provides a cookiecutter template that allows you to set up a Python project from scratch.

Requirements

• Linux based system (... sorry for all Windows users)
• cookiecutter

Use cookiecutter-python template

1. Install cookiecutter

2. Create new project by running:

   cookiecutter gh:milost/cookiecutter-python

After cookiecutter has successfully set up the project, you can run make in the root folder of the generated project directory to get a list of supported targets.

Set up project environment:

1. make install env=dev or make install for installing without development dependencies.
2. After the successful installation of the environment it can be activated by running the target make activate.
3. Next, it is advisable to put the newly created project into a version control system. Currently only this template supports only GitHub. To set up a repository, use the repo target and execute make repo. If you also want to create a remote repository on GitHub run make repo create-remote=true. This only creates a remote repository on GitHub but doesn't push your inital codebase, to do that, run make repo create-remote=true push=true. Remember for this target to work properly, you need to set a GitHub access token in the .env file.

---

NOTE! To use the following targets, you need to provide the corresponding tokens in the .env file:

1. make repo create-remote=true - requires a GITHUB_ACCESS_TOKEN
2. make publish - requires a PYPI_TOKEN
3. make docker-publish - requires a DOCKER_TOKEN
4. make test-publish - requires a CODECOV_TOKEN

---

Supported Targets

Setup targets

Target	Description
install-pyenv	Install pyenv and pyenv-virtualenv
install [env=dev]	Setup virtual environment and install project dependencies
activate	Activate the current project environment
flush-env	Delete the virtual environment for this project
reinstall	Deletes and recreates the virtual environment
repo [create-remote=true] [remote=URL] [push=true]	Create a git repository for the project

Development targets

Target	Description
run	Execute main method of python project
lint	Run linter (flake8) over project files
update	Update project dependencies
release [part=[major,minor,patch]]	Increment package version

Test targets

Target	Description
test [coverage=true] [show=true]	Run tests quickly with the default Python
test-upload	Upload test results to online services (codecov)

Build targets

Target	Description
build	Build sdist and wheel distributions
sdist	Build sdist distribution
wheel	Build wheel distribution
publish	Build distribution using build target and upload it to PyPi

Clean targets

Target	Description
clean	Clean build, python, and test artifacts
clean-build	Clean build artifacts
clean-pyc	Clean python artifacts
clean-test	Clean test artifacts

Documentation targets

Target	Description
docs [show=true]	Generate Sphinx HTML documentation, including API docs
import-docs	Import the current project to ReadTheDocs

Docker targets

Target	Description
docker-image	Build docker image
docker-rebuild	Rebuild docker image
docker-remove	Remove docker image
docker-publish	Push docker image to docker hub
docker-run	Execute the latest docker image
docker-service	Run Docker image as a service
docker-shell	Run Docker image as service and attach to it

Configure PyPI support

The unique repository upload token is found on the settings page of your project. You need write access to view this token.

Configure CodeCov support

The unique repository upload token is found on the settings page of your project. You need write access to view this token.

Configure Docker support

To be able to push your image to docker hub you need an access token. Instructions on how to generate an access token can be found here. Once you have an access token, you can set the DOCKER_TOKEN environment variable in the .env file which is located in the projects root directory.

Configure Documentation with ReadTheDocs

After the project has been created with cookiecutter, everything is already configured so that the documentation can be generated by ReadTheDocs. Once the repository has been is published on, say, GitHub, it can be imported into your ReadTheDocs account. To do this you can proceed as follows:

1. Login to ReadTheDocs using your GitHub account
2. Go to the ReadTheDocs dashboard
3. Click on Import a project
4. Choose the project for which you want the generate the documentation (the + button next to the project name)
5. On the next page, simply press the Next button and your project will be imported into ReadTheDocs.

From now on ReadTheDocs will keep track and generate a new project documentation for every new release.

Configure GitHub support

To be able to create a new GitHub repository for your project a personal access token is needed to access your GitHub account. Instructions on how to create a personal access token can be found here. Once the token has been created you can either set it as env variable yourself or set the GITHUB_ACCESS_TOKEN variable in the .env file. After that you can use the repo target to create a repository on GitHub over the command line by exexcuing make repo create-remote=true. If you want to immediately push your initial project setup to GitHub use make repo create-remote=true push=true.