Skip to content

Latest commit

 

History

History
136 lines (96 loc) · 8.73 KB

README.md

File metadata and controls

136 lines (96 loc) · 8.73 KB
Raw

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.