🧪 A modern Python template for scientific projects — with clean code, automated tests, documentation, citation, and publication tools, ready out-of-the-box.
This repository is designed to help researchers and developers (especially in the UHH Experimental Oceanography group quickly launch well-structured Python projects with consistent tooling for open science.
📘 Full documentation available at:
👉 https://eleanorfrajka.github.io/template-project/
- ✅ Example Python package layout:
template_project/*.py - 📓 Jupyter notebook demo:
notebooks/demo.ipynb - 📄 Markdown and Sphinx-based documentation in
docs/ - 🔍 Tests with
pytestintests/, CI with GitHub Actions - 🎨 Code style via
black,ruff,pre-commit - 📦 Package config via
pyproject.toml+ optional PyPI release workflow - 🧾 Machine-readable citation:
CITATION.cff
template-project/ ├── .github/ │ └── workflows/ # GitHub Actions for tests, docs, PyPI ├── docs/ # Sphinx-based documentation │ ├── source/ # reStructuredText + MyST Markdown + _static │ └── Makefile # for building HTML docs ├── notebooks/ # Example notebooks ├── template_project/ # Main Python package │ ├── init.py │ ├── _version.py │ ├── tools.py │ ├── readers.py │ ├── writers.py │ ├── utilities.py │ ├── plotters.py │ └── template_project.mplstyle # Optional: matplotlib style file ├── tests/ # Pytest test suite │ ├── test_tools.py │ └── test_utilities.py ├── .gitignore ├── .pre-commit-config.yaml ├── CITATION.cff # Sample file for citable software ├── CONTRIBUTING.md # Sample file for inviting contributions ├── LICENSE # Sample MIT license ├── README.md ├── pyproject.toml # Modern packaging config ├── requirements.txt # Package requirements ├── customisation_checklist.md # Development requirements └── requirements-dev.txt # Linting, testing, docs tools
Install in development mode:
git clone https://github.com/eleanorfrajka/template-project.git
cd template-project
# Option A: Using conda/mamba (recommended)
conda env create -f environment.yml
conda activate template-project
pip install -e .
# Option B: Using pip
pip install -r requirements-dev.txt
pip install -e .To run tests:
pytestTo build the documentation locally:
cd docs
make htmlContributions are welcome! Please also consider adding an issue when something isn't clear.
See the customisation checklist to adapt this template to your own project.
For information about planned improvements and the development roadmap, see MODERNIZATION_PLAN.md.
I'll also (once I know how) add instructions for how to publish the package to conda forge, so that folks who use conda or mamba for environment management can also install that way.
This repository includes a CITATION.cff file so that users of this template can include one in their own project.
There is no need to cite this repository directly.