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                                  
│       │       ├── mdakits-empty-favicon-template.svg
│       │       ├── mdakits-empty-logo-template.svg   
│       │       └── mdakits-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, 45 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:

  1. Create a new repository on GitHub . Do not initialize the repo with a README, license, or any other files.

  2. 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

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. Set up documentation

Documentation is important for your users and for yourself.

The documentation is built using Sphinx.

Generally, a project will have a few types of documentation:

  • User guide-type documentation, which explains how and why to use the package. While it may contain code examples, it’s typically more of a broad overview of package usage. For example, this page is user-guide-like documentation. A stub page for user-guide-like documentation is created in docs/source/getting_started.rst.

  • API documentation, which explains how to use the code. This is often automatically generated from docstrings in the code. A stub page for API documentation is created in docs/source/api.rst.

Documentation configuration

The documentation is configured in the docs/source/conf.py file. This file contains settings for the documentation, such as the project name, version, and theme. You can also add extensions to the documentation. More information on configuring Sphinx can be found in the Sphinx documentation.

By default, the documentation is built using the MDAnalysis theme sphinx theme using the default template MDAKits logo and favicon. You can change the theme by modifying the html_theme variable in docs/source/conf.py. You can also change the logo by either modifying the html_logo variable or by replacing the _static/logo/mdakits-placeholder-logo.png file. (This path is relative to the docs/source directory; the full path, relative to the repository root, is docs/source/_static/logo/mdakits-placeholder-logo.png.)

Similarly, you can change the favicon by replacing the html_favicon variable or by replacing the _static/logo/mdakits-empty-favicon-template.svg file.

You are welcome to either create an entirely custom logo and favicon or to use the provided templates. An mdakits-empty-logo-template.svg and mdakits-empty-favicon-template.svg are provided in the docs/source/_static/logo directory as templates for editing – feel free to place your logo within the gears!

Building the documentation

To build the documentation, you can use the following command:

$ cd docs
$ make html

This will build the documentation in the docs/build/html directory.

6. 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