What’s in This Template Project?

🐍 This project is designed for a Python-based code repository. It includes features to help you manage, test, document, and share your code.

Below is an overview of the files and folders you’ll find in the template-project, along with what they do and why they’re useful. If you’re new to GitHub or Python packaging, this is your orientation.

πŸ” Project Structure Overview

πŸ“· This is what the template looks like when you clone or fork it:

πŸ“ template-project File Structure

A minimal, modular Python project structure for collaborative research and reproducible workflows.

template-project/
β”œβ”€β”€ src/                          # [core] "src layout" β€” package lives here, not the repo root
β”‚   └── template_project/         # [core] Main Python package with scientific code
β”‚       β”œβ”€β”€ __init__.py           # [core] Makes this a Python package; exposes read/write/plot/process verbs
β”‚       β”œβ”€β”€ plotters/             # [core] Functions to plot data (transport.py, tables.py)
β”‚       β”œβ”€β”€ readers/              # [core] Functions to read raw data into xarray datasets
β”‚       β”‚   └── rapid.py          # [core] Example reader for a specific dataset (RAPID)
β”‚       β”œβ”€β”€ writers/              # [core] Functions to write data, e.g. to NetCDF (netcdf.py)
β”‚       β”œβ”€β”€ processors/           # [core] Unit conversion, calculations, etc. (units.py)
β”‚       β”œβ”€β”€ logger.py             # [core] Structured logging configuration for reproducible runs
β”‚       β”œβ”€β”€ template_project.mplstyle # [core] Default plotting parameters
β”‚       └── utilities.py          # [core] Helper functions (e.g., file download or parsing)
β”‚
β”œβ”€β”€ tests/                        # [test] Unit tests using pytest
β”‚   β”œβ”€β”€ test_readers.py           # [test] Test functions in readers/
β”‚   β”œβ”€β”€ test_processors.py        # [test] Test functions in processors/
β”‚   β”œβ”€β”€ test_utilities.py         # [test] Test functions in utilities.py
β”‚   └── ...
β”‚
β”œβ”€β”€ docs/                         # [docs]
β”‚   β”œβ”€β”€ source/                   # [docs] Sphinx documentation source files
β”‚   β”‚   β”œβ”€β”€ conf.py               # [docs] Setup for documentation
β”‚   β”‚   β”œβ”€β”€ index.rst             # [docs] Main page with menus in *.rst
β”‚   β”‚   β”œβ”€β”€ setup.md              # [docs] One of the documentation pages in *.md
β”‚   β”‚   β”œβ”€β”€ template_project.rst  # [docs] The file to create the API based on docstrings
β”‚   β”‚   β”œβ”€β”€ ...                   # [docs] More *.md or *.rst linked in index.rst
β”‚   β”‚   └── _static               # [docs] Figures
β”‚   β”‚       β”œβ”€β”€ css/custom.css    # [docs, style] Custom style sheet for docs
β”‚   β”‚       └── logo.png          # [docs] logo for top left of docs/
β”‚   β”œβ”€β”€ environment.yml           # [docs, meta] Conda env (python 3.11 + pandoc + pip install -e .[dev])
β”‚   └── Makefile                  # [docs] Build the docs
β”‚
β”œβ”€β”€ notebooks/                    # [demo] Example notebooks
β”‚   β”œβ”€β”€ demo.ipynb                # [demo] Also run in docs.yml to appear in docs
β”‚   └── ...
β”‚
β”œβ”€β”€ data/                         # [data]
β”‚   └── moc_transports.nc         # [data] Example data file used for the template.
β”‚
β”œβ”€β”€ logs/                         # [core] Log output from structured logging
β”‚   └── <ARRAY>_<timestamp>_read.log  # [core] e.g. MOVE_20260707T10_read.log
β”‚
β”œβ”€β”€ .github/                      # [ci] GitHub-specific workflows (e.g., Actions)
β”‚   β”œβ”€β”€ workflows/
β”‚   β”‚   β”œβ”€β”€ docs.yml              # [ci] Test build documents on *pull-request*
β”‚   β”‚   β”œβ”€β”€ docs_deploy.yml       # [ci] Build and deploy documents on "merge"
β”‚   β”‚   β”œβ”€β”€ pypi.yml              # [ci] Package and release on GitHub.com "release"
β”‚   β”‚   └── test.yml              # [ci] Run pytest on tests/test_<name>.py on *pull-request*
β”‚   β”œβ”€β”€ ISSUE_TEMPLATE.md         # [ci, meta] Template for issues on Github
β”‚   └── PULL_REQUEST_TEMPLATE.md  # [ci, meta] Template for pull requests on Github
β”‚
β”œβ”€β”€ .gitignore                    # [meta] Exclude build files, logs, data, etc.
β”œβ”€β”€ pyproject.toml                # [ci, meta, style] Build system, dependencies (test/docs/dev extras), ruff config
β”œβ”€β”€ CITATION.cff                  # [meta] So Github can populate the "cite" button
β”œβ”€β”€ README.md                     # [meta] Project overview and getting started
└── LICENSE                       # [meta] Open source license (e.g., MIT as default)

The tags above give an indication of what parts of this template project are used for what purposes, where:

  • # [core] – Scientific core logic or core functions used across the project.

  • # [docs] – Documentation sources, configs, and assets for building project docs.

  • # [test] – Automated tests for validating functionality.

  • # [demo] – Notebooks and minimal working examples for demos or tutorials.

  • # [data] – Sample or test data files.

  • # [ci] – Continuous integration setup (GitHub Actions).

  • # [style] – Configuration for code style, linting, and formatting.

  • # [meta] – Project metadata (e.g., citation info, license, README).

Note: There are also files that you may end up generating but which don’t necessarily appear in the project on GitHub.com (due to being ignored by your .gitignore). These may include your environment (venv/, if you use pip and virtual environments), distribution files dist/ for building packages to deploy on http://pypi.org, htmlcov/ for coverage reports for tests, template_project_efw.egg-info for editable installs (e.g., pip install -e .).

πŸ” Notes

  • Modularity: Code is split by function (reading, writing, tools).

  • Logging: All major functions support structured logging to logs/.

  • Tests: Pytest-compatible tests are in tests/, with one file per module.

  • Docs: Sphinx documentation is in docs/.

πŸ”° The Basics (Always Included)

  • README.md – The first thing people see when they visit your GitHub repo. Use this to explain what your project is, how to install it, and how to get started.

  • LICENSE – Explains what others are allowed to do with your code. This template uses the MIT License:

    • βœ… Very permissive β€” allows commercial and private use, modification, and distribution.

    • πŸ”— More license info: choosealicense.com

  • .gitignore – Tells Git which files/folders to ignore (e.g., system files, data outputs).

  • pyproject.toml – Declares the Python packages your project needs to run, plus optional test, docs, and dev extras.

🧰 Python Packaging and Development

  • pyproject.toml – A modern configuration file for building, installing, and describing your package (e.g. name, author, dependencies). Runtime dependencies plus the test, docs, and dev extras (testing, linting, formatting, docs tools) are all declared here.

  • src/template_project/ – Your main code lives here, under a top-level src/ directory (the β€œsrc layout”). Keeping the package out of the repo root means tests import the installed package rather than the working copy. Python treats this as an importable module (the import name is still template_project).

  • pip install -e ".[dev]" – Installs your project locally (editable) together with the full development toolchain, updating as you edit files.

πŸ§ͺ Testing and Continuous Integration

  • tests/ – Folder for test files. Use these to make sure your code works as expected.

  • .github/workflows/ – GitHub Actions automation:

    • tests.yml – Runs your tests automatically when you push changes.

    • docs.yml – Builds your documentation to check for errors.

    • docs_deploy.yml – Publishes documentation to GitHub Pages.

    • pypi.yml – Builds and uploads a release to PyPI when you tag a new version.

πŸ“ Documentation

  • docs/ – Contains Sphinx and Markdown files to build your documentation site.

    • Run make html or use GitHub Actions to generate a website.

  • .vscode/ – Optional settings for Visual Studio Code (e.g., interpreter paths).

  • notebooks/ – A place to keep example Jupyter notebooks.

🧾 Metadata and Community

  • CITATION.cff – Machine-readable citation info. Lets GitHub generate a β€œCite this repository” button.

  • CONTRIBUTING.md – Guidelines for contributing to the project. Useful if you welcome outside help.

  • docs/environment.yml – Conda/mamba environment for building the docs (python 3.11 + pandoc, then pip install -e .[dev]).

πŸ€– Automation Features

This template includes several automation features to streamline development:

Dependabot (Dependency Updates)

  • File: .github/dependabot.yml

  • Purpose: Automatically creates PRs to update Python dependencies and GitHub Actions

  • Schedule: Weekly on Mondays

  • To disable: Delete .github/dependabot.yml or comment out the package ecosystems you don’t want

Towncrier (Automated Changelog)

  • Files: pyproject.toml ([tool.towncrier] section), changelog.d/

  • Purpose: Generates changelogs from fragment files

  • Usage: Create .md files in changelog.d/ describing changes, then run towncrier build

  • To disable:

    • Remove towncrier from the dev extra in pyproject.toml

    • Remove [tool.towncrier] section from pyproject.toml

    • Delete changelog.d/ directory

Linting & Formatting (Ruff)

  • Config: [tool.ruff] section of pyproject.toml

  • Purpose: ruff handles both linting and formatting; the CI lint job runs ruff check . and ruff format --check . on every pull request

  • Note: This project does not use pre-commit; linting is enforced CI-side. See the linting & formatting guide.

Note: These automation features are optional but recommended for maintaining code quality and staying up-to-date with dependencies.

βœ… Summary

This template is a starting point for research or open-source Python projects. It supports:

  • Clean project structure

  • Reproducible environments

  • Easy testing

  • Auto-publishing documentation

  • Optional packaging for PyPI

πŸ’‘ Use what you need. Delete what you don’t. This is your scaffold for doing good, shareable science/code.