copyme

A simple template for python development. Use this repository as a template for developing a python library or package.

[!NOTE] Check out the documentation website

Templates

When copying files from this repo, remember that they are templates. So:

1. look for [CHANGE THIS] for mandatory modifications;
2. look for [CHECK THIS] for possible modifications;
3. look for [EXAMPLE] for simple examples (comment or uncomment it if needed);
4. look for [ADD MORE IF NEDDED] for possible extra features;
5. placeholders are designated by curly braces: {replace-this}.

Configuration files

This repository relies on several configuration files that are essential for the proper functioning of the template. Each file has a specific role, and some of them work together, so they should be edited thoughtfully. Below is an overview of the main configuration files and what you should know about them.

[!NOTE]
All config files are commented with recommended actions and extra steps.

[!WARNING]
Online documentation build may require additional setup — check .github/workflows/docs.yml.

[!IMPORTANT]
Continous Integration (CI) setup allows for check-ups for commits and not allowing bad code to be pushed to the main branch. So Style, Docs and Tests must always pass.

Repo layout

A standard python repo may use the following layout. This layout is known as src layout, since it stores the source code under a src/{repo} folder.

See more on flat vs src layout

{repository}/
│
├── LICENSE
├── README.md                     # [CHECK THIS] this file (landing page)
├── .gitignore                    # [CHECK THIS] configuration of git vcs ignoring system
├── pyproject.toml                # [CHECK THIS] configuration of python project
├── MANIFEST.in                   # [CHECK THIS] configuration of source distribution
|
├── .github/                      # github folder
│    └── workflows/               # folder for continuous integration services
│         ├── style.py            # [CHECK THIS] configuration file for style check workflow
│         ├── tests.py            # [CHECK THIS] configuration file for tests workflow
│         └── docs.yml            # [CHECK THIS] configuration file for docs build workflow
│
├── dev/                          # development folder
│    ├── checkout.py              # checkout script
│    ├── docs.py                  # build docs script
│    ├── style.py                 # style script
│    ├── tests.py                 # testing script
│    └── templates-ci/            # templates for CI
│
├── docs/                         # documentation folder
│    ├── about.rst                # info about the repo
│    ├── api.rst                  # api reference using sphinx autodoc
│    ├── conf.py                  # [CHECK THIS] configuration file for sphinx
│    ├── dummy.md                 # markdown docs also works
│    ├── index.rst                # home page for documentation
│    ├── usage.rst                # instructions for using this repo
│    ├── make.bat                 # (optional) [generated] sphinx auxiliar file 
│    ├── Makefile                 # (optional) [generated] sphinx auxiliar file 
│    ├── figs/                    # figs-only files         
│    ├── data/                    # docs-only data
│    ├── generated/               # [generated] sphinx created files 
│    ├── _templates/              # [ignored] [generated] sphinx created stuff
│    ├── _static/                 # [generated] sphinx created stuff
│    └── _build/                  # [ignored] [generated] sphinx build
│
├── src/                          # source code folder
│    ├── {repository}.egg-info    # [ignored] [generated] files for local development
│    └── {repository}/            # [CHANGE THIS] source code root
│         ├── __init__.py         # template init file
│         ├── module.py           # template module
│         ├── ...                 # develop your modules
│         ├── mypackage/          # template package
│         │    └── submodule.py
│         └── data/               # run-time data
│
├── examples/                     # (optional) learning resources 
│    ├── examples_01.ipynb    
│    └── examples_02.ipynb            
│
└── tests/                        # testing code folder
     ├── conftest.py              # [CHECK THIS] configuration file of tests
     ├──unit/                     # unit tests package     
     │    └── test_module.py      # template module for unit tests
     ├── bcmk/                    # benchmarking tests package
     │    └── test_bcmk.py        # template module for benchmarking tests
     ├── data/                    # test-only data
     │     ├── test_data.csv
     │     ├── datasets.csv       # table of remote datasets
     │     └── dataset1/          # [ignored] subfolders in data
     └── outputs/                 # [ignored] tests outputs