Usage

Getting up and running requires a short process.

You will need the following:

Python 3.9+
The cookiecutter tool installed
A GitHub account

1. Use the cookiecutter to create a new project

An example of using the cookiecutter is illustrated below. The first line is the prompt, i.e. the actual command to use. It is followed by all the prompts you can expect, and some example answers.

$ cookiecutter gh:MDAnalysis/cookiecutter-mdakit
  [1/11] project_name (ProjectName): My Project Name
  [2/11] repo_name (my_project_name): example-repository
  [3/11] package_name (example_repository): package_name
  [4/11] description (A short description of the project.): A package to do MD analysis
  [5/11] github_username (Your personal GitHub username): my-github-username
  [6/11] github_host_account (GitHub account for hosting example-repository 
(e.g. my-github-username or an organization account). Press Enter to use 
my-github-username): 
  [7/11] author_name (Your name (or your organization/company/team)): My Name
  [8/11] author_email (Your email (or your organization/company/team)): my_example_email@gmail.com
  [9/11] Select dependency_source
    1 - Prefer conda-forge over the default anaconda channel with pip fallback
    2 - Prefer default anaconda channel with pip fallback
    3 - Dependencies from pip only (no conda)
    Choose from [1/2/3] (1): 
  [10/11] Select include_ReadTheDocs
    1 - y
    2 - n
    Choose from [1/2] (1): 
  [11/11] template_analysis_class (Class name to template (e.g. MyProjectName ).
Press Enter to skip including analysis templates): MyAnalysisClass

This generates the output skeleton:

example-repository                         
├── .codecov.yml                              <- Settings for Codecov
├── .gitattributes                         
├── .github                                   <- GitHub hooks for user contribution, pull request guides and GitHub Actions CI
│   ├── ISSUE_TEMPLATE                        <- Templates for opening issues on GitHub
│   │   ├── bug_report.md                  
│   │   └── feature_request.md             
│   ├── PULL_REQUEST_TEMPLATE.md              <- Template for opening a pull request on GitHub
│   └── workflows                             <- where the configuration for CI lives
│       └── gh-ci.yaml                     
├── .gitignore                                <- Stock helper file telling git what file name patterns to ignore when adding files
├── .pre-commit-config.yaml                   <- Settings for pre-commit hooks for flake8 and isort
├── .pylintrc                                 <- Settings for PyLint
├── AUTHORS.md                                <- List of all contributors to the package
├── CHANGELOG.md                              <- Log of changes in each release
├── CODE_OF_CONDUCT.md                        <- Code of Conduct for developers and users
├── CONTRIBUTING.md                           <- Guide to contributing
├── LICENSE                                   <- License file
├── MANIFEST.in                               <- Packaging information for pip
├── README.md                                 <- Description of project which GitHub will render
├── devtools                                  <- Environment and other development tools
│   └── conda-envs                            <- Conda environments for testing
│       └── test_env.yaml                     <- Default test environment file
├── docs                                      <- Documentation template folder with many settings already filled in
│   ├── Makefile                           
│   ├── README.md                             <- Instructions on how to build the docs
│   ├── make.bat                           
│   ├── requirements.yaml                     <- Documentation building specific requirements. Usually a smaller set than the main program
│   └── source                             
│       ├── _static                        
│       │   ├── README.md                  
│       │   └── logo                       
│       │       ├── placeholder_favicon.svg
│       │       └── placeholder_logo.png   
│       ├── _templates                     
│       │   └── README.md                  
│       ├── api.rst                        
│       ├── conf.py                        
│       ├── getting_started.rst            
│       └── index.rst                      
├── package_name                           
│   ├── __init__.py                        
│   ├── analysis                           
│   │   ├── __init__.py                    
│   │   └── myanalysisclass.py             
│   ├── data                                  <- Sample additional data (non-code) which can be packaged
│   │   ├── README.md                      
│   │   ├── __init__.py                    
│   │   ├── files.py                          <- Recommended file for resolving data file names
│   │   └── mda.txt                           <- Just an example, delete in production
│   └── tests                                 <- Unit test directory with sample tests
│       ├── __init__.py                    
│       ├── analysis                       
│       │   ├── __init__.py                
│       │   └── test_myanalysisclass.py    
│       ├── conftest.py                       <- File for common pytest fixtures
│       ├── test_package_name.py              <- Example test file
│       └── utils.py                       
├── pyproject.toml                            <- Dependencies for pip
└── readthedocs.yaml                          <- Settings for ReadTheDocs
                                           
16 directories, 44 files                   
                                           

We will go more into these files in the rest of this tutorial, as well as other sections in this documentation. Please see Options for more details.

2. Add the project to GitHub

The generated repository should be an initialised git repository. We now need to connect it to GitHub:

Create a new repository on GitHub . Do not initialize the repo with a README, license, or any other files.
Push the local repository to GitHub. GitHub should provide instructions for doing so, but in short:
- Add the remote named origin with git remote add origin <URL>
- Push the local repository to the remote repository with git push -u origin main
- Verify files were pushed successfully by checking on GitHub

3. Link external hooks

The generated repository contains configuration files for several external services. These need to be manually linked to each service to run.

Documentation: ReadTheDocs

ReadTheDocs builds documentation automatically for you from the files in docs/. To link ReadTheDocs, ensure that you have a ReadTheDocs account; you should be able to use your GitHub account. To link the project, click the Import a Project button on the dashboard.

We strongly recommend turning on building documentation for your pull requests to check and preview your docs. To do so:

Go to the Admin tab
Go to Advanced Settings
Tick the “Build pull requests for this project” checkbox
Scroll down and remember to click “Save”!

Further configuration can be done on ReadTheDocs or in the readthedocs.yaml file.

Test coverage: Codecov

Sign up at Codecov and set up this repository by adding the GitHub App Integration. You may need to trigger some tests and wait a few hours before seeing coverage reports appearing on Codecov. You can use these reports to discover which parts of your code are not checked by your current tests. You should ideally aim for >90% code coverage to ensure that your package actually does what you think it does!

The .codecov.yml file contains configuration for Codecov. Edit that file to modify settings, such as files to ignore and what to include in the coverage report.

4. Make and push changes to your code

Now you should go forth and code! To keep things clean and simple, we advise a few tips:

Always work in a virtual environment like conda. You can create a development environment by following the instructions in the README. In short:

conda create --name <environment_name> python=3.8
conda activate <environment_name>  # remember to do this every time
conda env update --name <environment_name> --file devtools/conda-envs/test_env.yaml
conda env update --name <environment_name> --file docs/requirements.yaml

Always work in a separate branch. The main branch is the default, or central, branch. All development work should be done in a separate branch to avoid messing up the main branch, or to allow you to work on different approaches at the same time. This also allows multiple people to work on the code at the same time. Create a new branch with git checkout -b <my_branch_name>. See GitHub’s documentation on branches for more information.
When you feel ready, open a pull request on GitHub. This does not have to be when you think you have finished the code! A PR runs tests and builds documentation. This will allow others to review your code and help you make sure it is correct. It’s always a good way to get feedback and validation, as well as collaborate with other people. See GitHub’s documentation on PRs for more information.

5. Tagging versions of your code

Tagging versions of your code is a good way to keep references to specific versions of your code that don’t change. This is especially useful when you want to make a new code release. The cookiecutter uses versioningit to automatically determine your package’s version based on git tags.

By default, versioning will start from 0.0.0. You can install versioningit to check the current versioningit output from commandline:

$ cd <my_package_directory>
$ versioningit .
0.0.0

As you add commits, the versioning will automatically update with the commit hashes:

$ versioningit .
0.0.0+1.g58bcaff

To tag a version, use the following command:

git tag -a 0.1.0 -m "Version 0.1.0"

This will create a tag called 0.1.0 with the message “Version 0.1.0”. You can then push this tag to GitHub with git push origin --tags.

After creating a tag, you can check the versioning again:

$ versioningit .
0.1.0