This repository contains a cookiecutter template for generating a scientific Python project complete with CI testing and documentation. See the usage section below for a quick start on how to obtain the template.
The repository also hosts an accompanying tutorial that provides guided and detailed instructions about how to set up and use the template and all of the features it contains. If you are new to cookiecutters and Python packaging, then it is recommended to head there first.
The original version of these resources were produced by Brookhaven National Lab, and this repository was forked from theirs to add support for GitLab and tailor it to UKAEA guidelines. Overall, it maintains a fairly generic resource that should be valuable for any researcher, but there are a few hyperlinks that point to internal UKAEA websites.
On the command line, navigate to the directory where you would like to put your project, and issue this command:
cookiecutter https://github.com/ukaea/scientific-python-cookiecutterFollow the prompts to set up your project.
The tutorial is aimed at scientific researchers who have a novice level of experience with Python. Typically, this means a researcher who knows the basic features of Python and has written a few scripts to perform analysis and visualisation but has little or no awareness about how to package Python projects so they can be shared. However, even if you consider yourself to be above novice level, this tutorial could prove useful because it recommends a consistent set of tools and practices that all successful Python projects should have.
You will be guided through setting up the following:
- Version control for your project on GitHub or GitLab.
- Creating a virtual environment for dependency management.
- Documenting your code with Sphinx and publishing your documentation.
- Tests for your code with pytest.
- Continuous integration on Travis CI (for GitHub projects) or GitLab CI.
- Publishing releases of your software and making it available on PyPI.