Cookiecutter for Birdhouse

Documentation Status Travis Build GitHub license Join the chat at https://gitter.im/bird-house/birdhouse

A Cookiecutter template for a Birdhouse bird package

Cookiecutter is a command-line utility to create projects from templates. This cookiecutter-birdhouse template creates a barebone PyWPS server adhering to Birdhouse conventions. It comes complete with a framework for installation, configuration, deployment, documentation and tests. It even includes a Dockerfile for containerization! Create your project then get started writing new WPS processes in minutes.

Warning

This is the cookiecutter template for PyWPS without the Buildout deployment. The template for the Buildout deployment is on branch 0.2.x.

Features

  • Ready-made PyWPS server (a bird)

  • Pre-configured .travis.yml for Travis-CI automated deployment and testing

  • Pre-configured .codacy.yml for automated Codacy code review

  • A Dockerfile and docker-compose.yml for containerization

  • Preconfigured Sphinx documentation that can be hosted on ReadTheDocs

  • A Makefile to install the code, start, stop and poll the server and more

Installation

Prior to installing cookiecutter-birdhouse, the cookiecutter package must be installed in your environment. This is achieved via the following command:

$ conda install -c conda-forge cookiecutter

With cookiecutter installed, the cookiecutter-birdhouse template can be installed with:

$ cookiecutter https://github.com/bird-house/cookiecutter-birdhouse.git

Once cookiecutter clones the template, you will be asked a series of questions related to your project:

$ full_name [Full Name]: Enter your full name.

$ email [Email Address]: Enter your email address.

$ github_username [bird-house]: Accept the default or enter your github username.

$ project_name [Babybird]: The name of your new bird.

$ project_slug [babybird]: The name of your bird used as Python package.

$ project_short_description [Short description]: Enter a short description about your project.

$ version [0.1.0]: Enter the version number for your application.

$ http_port [5000]: The HTTP port on which your service will be accessible.

$ https_port [25000]: The HTTPS port on which your service will be accessible.

$ output_port [8090]: The HTTP port on which your service outputs will be accessible.

Usage

After answering the questions asked during installation, a bird Python package will be created in your current working directory. This package will contain a configurable PyWPS service with some initial test processes.

Then:

  • Create a repo and put it there.

  • Add the repo to your Travis-CI account.

  • Add the repo to your ReadTheDocs account + turn on the ReadTheDocs service hook.

For more details, see the cookiecutter-pypackage tutorial.

See the babybird example of a generated bird.

Development

If you want to extend the cookiecutter template then prepare your development environment as follows:

# clone repo
$ git clone git@github.com:bird-house/cookiecutter-birdhouse.git

# change into repo
$ cd cookiecutter-birdhouse

# create conda environment
$ conda env create -f environment.yml

# activate conda environment
$ source activate cookiecutter-birdhouse

# run tests
$ make test

# bake a new bird with default settings
$ make bake

# the new "baked" bird is created in the cookies folder
$ ls -l cookies/
babybird

# well ... you know what to do with a bird :)

# finally you may clean it all up
$ make clean

Bump a new version

Make a new version of this Cookiecutter in the following steps:

  • Make sure everything is commit to GitHub.

  • Update CHANGES.rst with the next version.

  • Dry Run: bumpversion --dry-run --verbose --new-version 0.3.1 patch

  • Do it: bumpversion --new-version 0.3.1 patch

  • … or: bumpversion --new-version 0.4.0 minor

  • Push it: git push --tags

See the bumpversion documentation for details.