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.
Note
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¶
Attention
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:
make
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:
- Cuts a dummy project and runs all tests inside (See Project Testing)
- 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).