The audience for this project is the Hydrology group at KIT (https://hyd.iwg.kit.edu). However this is simply a setuptools driven project template, which can be used for any purpose.
The documentation can be found at: http://hyd-template.readthedocs.io
This template can be used to publish your own Python code and make it usable in other projects. Following this template your own code will:
- be installable via pip
- install all its requirements automatically
- have a valid license and attribution information
- obviously be accessible on GitHub
- add unittest to provide code safety
- use Travis-CI to run the tests automatically
- use ReadTheDocs to add proper documentation to your project.
The main benefits are the tremendously improved usability of your code. Potential users can install your package with one line of code and see if building works, the tests run without error and how much of your code they cover. Last but not least, with GitHubPages or Read the Docs you have two great tools to supply your user with any kind of additional information.
So how does this packages look like?
First of all, on the main project level you will find a number of important files and folders:
The first and most important folder will contain the Python package itself. This is what will be installed at the users computer in case he installs your package using pip. Anything outside of this folder is used to setup the Git project, produce meta-data for the Python Package Index (PyPI) and will contain the documentation.
| root folder | Description |
|---|---|
| package_template | This is your actual Python project folder |
| docs | This is the folder used for producing documentation. |
| README.md | use this file to produce a first overview for your project. Keep in mind that this is the first (and maybe only) page the user will visit. |
| LICENSE | This is the MIT license. Keep it or replace it |
| .gitignore | git file. Specify all file types that should not be synchronized with the package, like data, config or development files |
| MANIFEST.in | This files 'includes' all non-python files that shall be installed along with the package, when installed using pip. This is typically the README.md or LICENSE file |
| requirements.txt | This file should contain all Python dependencies for your package. pip will take care of installing them. Each dependency goes into its own line. If a minimum version is required, place it like: `numpy>=0.12` to install at least Version 0 .12 of numpy |
| requirements-rtd.txt | These are slightly different requirements needed on the readthedocs.org server to build the documentation correctly. |
| VERSION | place the version number here. You could e.g. increment the number whenever you push a new version on PyPI or onto a 'stable' branch in GitHub. I do it this way to not push every litte bugfix or typo fix into a new version. |
| .travis.yml | This is the configuration file for Travis-CI. You will need to log into [Travis](https://travis-ci.org) with you github account to enable automatic buildings |
| setup.py | This is the main installation file. pip will run exactly this file after installing the requirements. Everything that is necessary to make your package work, like generating default configuration or whatever, should go into this file. Do not fortget to adapt this file to your needs. This file will also set up all the meta-data for PyPI |