1   Cookiecutter Template

1.1   Setup

cookiecutter-ds-docker requires these tools as a prerequisite:

  • docker
  • homebrew (Optional for Mac OSX)
  • Python cookiecutter

1.1.1   Installing Docker

Please follow the instructions in the official Docker documentation.


We suggest using Docker 18.09 or higher.

1.1.2   (Optional) Installing homebrew in Mac OSX

homebrew is the easiest way to install cookiecutter in Mac OSX (see below). Please follow the instructions in the official website, if you wish to install homebrew.

1.1.3   Installing cookiecutter

cookiecutter is quite straightforward to install in many modern systems. For example, you can install cookiecutter in Debian-based Linux distributions (e.g., Ubuntu) and Mac OSX by:

OS Command
Debian-based Linux sudo apt install cookiecutter
Mac OSX brew install cookiecutter

Please refer to the official cookiecutter documentation for alternatives.

1.2   Cutting a New Project

To “cut” a new project from the template, run on the terminal:

cd /{ base_folder }
cookiecutter https://github.com/sertansenturk/cookiecutter-ds-docker

cookiecutter will ask you to fill a few variables, namely:

Variable Explanation Modifies
repo_name Name of the repository Header of README.md
repo_slug Slug of the repository name Repository folder name, GitHub URL, explanations in the documentation
package_name Name of the Python package in the project Python package name, setup.py, tox.ini, unittests, docker image names, explanations in the documentation
author_name Name of the authoring person/team/organization Author name in setup.py and the documentation
author_email E-mail to contact the author Author e-mail in setup.py, CODE_OF_CONDUCT.md and the documentation
github_username Github username GitHub URL, URLs in setup.py, docker image names, explanations in the documentation
description A short description of the project Explanations in setup.py and the documentation

Afterward, the project will be created in /{ base_folder }/{{ cookiecutter.repo_slug }}.

For additional command-line options, please refer to the advanced options in the official cookiecutter documentation.

1.3   Local Usage


You should clone the repo if you would like to use cookiecutter-ds-docker locally or modify the template:

git clone https://github.com/sertansenturk/cookiecutter-ds-docker.git
cd cookiecutter-ds-docker

Below, we introduce some useful Makefile commands to interact with cookiecutter-ds-docker. For all available commands, please refer to the help by running:

make help

1.3.1   Cutting a New Project Locally

You can cut a project by running:


and entering the variables, as explained above. The project will be created at ../{{ cookiecutter.repo_slug }} relative to the ./cookiecutter-ds-docker folder.

1.3.2   Documentation

The documentation is hosted online at Read the Docs. Read the Docs automatically publishes and updates a version for the master branch, dev branch, and each release in Github.

If you would like to build the documentation locally, you need to run:

make sphinx-html

The above command builds a docker image called sertansenturk/sphinx. It then runs a container from the image and renders the documentation using Sphinx.

Afterward, you can access the documentation by opening ./docs/_build/html/index.html on your browser.

To validate the documentation without building, run:

make sphinx-html-test

1.3.3   Running Tests Locally

You can run the tests with a single command by:

make test

The above command:

  1. Cuts a dummy project and runs all tests inside (See Project Testing)
  2. Validates the Sphinx documentation (See above)

1.4   Tests in Travis CI

cookiecutter-ds-docker has Travis CI integration (link), where all of the tests above are run automatically after each push.

Travis CI also generates code coverage reports for the starter Python package (see Python Tests in the Project), which can be viewed on codecov (link).