Template repository for python packages

Overview

Minimize thinking when setting up your new python project. This (minimal) template project and the following set of instructions will allow you to get

• Standard python packaging structure
• Make a git-clone of your package pip installable
• Test your package automatically with pytest on Travis-ci
• Build and publish the documentation on github.io

How to use

1. Create your (empty) project on github: https://github.com/username_or_organization/new_project

2. Activate Travis-ci for your project. Follow this step of the tutorial.

3. To allow the auto-deployment of the documentation to github pages

   1. On github, in your repo settings, in the GitHub Pages section, set the gh-pages branch as the source
   2. On github, in your account setting, in the developer settings, generate a new personal access token (e.g., note Travis-sphinx, scope repo)
   3. On Travis, in your repo settings, set a variable called GH_TOKEN with value equal to the token you just created

4. On your local machine, clone this template and push it to your new repo

   git clone --bare https://github.com/dpole/python-template.git
   cd python-template
   git reset $(git commit-tree HEAD^{tree} -m "Template")
   git push --mirror https://github.com/username_or_organization/new_project
   cd ..
   rm -rf python-template

5. Edit your package

   1. Edit this README. Remember to replace dpole with username_or_organization and python-template with new_project in the urls of the badges (see the image at the top of the file).
   2. Rename the package_name folder with the name of your package, edit and/or rename the files in it (don't forget __init__.py).
   4. Edit the setup.py file. Don't forget to add the dependencies of your package in the isntall_requires list.
   5. Edit every file in the docs/source folder and subfolders.
   6. After the first minimal commit run git reset $(git commit-tree HEAD^{tree} -m "First commit"), which will erase the history of the tempalte's master branch from the one of your repository
   7. Write doctrings using the numpy sphinx syntax