This is a template for starting your Python projects at CWI’s computational imaging group.

This template lets you easily set up a Python package for your own projects. It automatically creates a directory tree with sensible locations for your code, documentation and tests, and directly makes a number of useful tools available to more conveniently install, document and eventually publish your project.

This template is BSD licensed.

Features include:

• Boilerplate for documentation with Sphinx
• Boilerplate for unit testing
• Setup configuration
• Conda packaging
• Software License
• A good initial README file
• Various files such as a changelog, a contributor guide, and more.

Install the latest Cookiecutter if you haven’t installed it yet (this requires Cookiecutter 1.4.0 or higher):

pip install -U cookiecutter

To generate a new project, execute the following in your terminal:

cookiecutter https://github.com/cicwi/cookiecutter-cicwi.git

Cookiecutter will ask you some questions to get your project started.

To start using version control execute the following code

cd your-project-name
git init                       # Initialized the git repository
git add .                      # Stages all files
git commit -m "Initial commit" # Creates an initial commit

You can also create a GitHub repository. Once you have one, push your code there by executing

git remote add origin git@github.com:<your-GitHub-username>/<your-project-name>.git
git push -u origin master

It is recommended you create a separate conda environment for each project you work on. Do this by executing

conda create -n <your-project-name> python=3.6
source activate <your-project-name>

Note the python=3.6 in the command-line above. The project template works best for versions of Python 3.6 and higher. In fact, it has not been tested and might not work for older versions of Python at all.

The following command does two things. First of all, it installs your newly created package as “editable” into the Conda environment. This means that any change you make to the source files is reflected in the ‘installed’ package. Secondly, this command installs some required development tools used for documentation, testing, and linting.

make install_dev

Of course, once this is done, you can start writing software. You can start by extending the script in examples/getting_started.py, or create more scripts in the examples directory. Once you identify common functionality, you can add functions to the main module file in your_project_slug/your_project_slug.py. The getting_started.py file contains examples how to call these functions.

To make your code usable for others, it is a good idea to have documentation, publish a Conda package, and release versioned code.

In your project’s README.md, you will find a checklist with steps to guide to a first release.

In any case, do not forget to:

1. Update the README
2. Keep a CHANGELOG
3. Update your documentation using make docs
4. Create GitHub pages documentation
5. Update version in VERSION file for a new release
6. Create releases on GitHub

If you create a new project called human_readable_project_name, the following files will be created:

.
├── CHANGELOG.md                       # The changelog
├── conda                              # Conda packaging metadata
│   ├── build.sh
│   ├── conda_build_config.yaml
│   └── meta.yaml
├── CONTRIBUTING.rst                   # Contributor guide
├── doc_sources                        # Boilerplate for documentation generation
│   ├── conf.py
│   ├── index.rst
│   ├── ...
├── examples                           # Example scripts
│   ├── getting_started.py
├── human_readable_project_name        # Main source code directory
│   ├── human_readable_project_name.py # Main module
│   ├── __init__.py                    # Module dir
│   └── VERSION                        # Version file
├── LICENSE.md                         # License
├── Makefile                           # Makefile: contains common 'make' recipes (see below)
├── MANIFEST.in                        # Boilerplate used for packaging
├── README.md                          # Readme
├── setup.cfg                          # Configuration for python tooling
├── setup.py                           # Packaging information for the package
└── tests                              # Boilerplate for unit testing
    ├── __init__.py
    └── test_human_readable_project_name.py

The project comes with a default Makefile. The Makefile has a reasonable number of built-in commands.

Download and install development requirements into your current conda environment with

make install_dev

This command also install your current project as an “editable” project into your current Conda environment. This means that any change to your source files will be reflected in the “installed” environment.

Download and install your project requirements into your current conda environment with

make install

Update your documentation with

make docs

Automatically reformat the code of your project to a common format with

make style

The command

make conda_package

builds a conda package, which you can share on https://anaconda.org/.

• Allard Hendriksen
• Jan-Willem Buurlage
• Willem Jan Palenstijn
• Daniël Pelt

Contributions are always welcome. Please submit a pull request.

If you have any issues, questions, or remarks, then please open an issue on GitHub.

This template is based on Audrey Roy Greenfeld’s cookiecutter-pypackage.

This project is licensed under the BSD License - see the LICENSE file for details