Getting Started
The page demonstrates the basic usage of the MDAKit cookiecutter to generate a skeleton for a Python package. Once created, you will then need to add code to and customise your package; this is covered in the next section.
Requirements
- You will need the following:
Python 3.9+
The cookiecutter tool installed
A GitHub account
Basic Usage
To run the cookiecutter, run the followign command:
$ cookiecutter gh:MDAnalysis/cookiecutter-mdakit
You will be prompted to answer a series of questions to begin the initial customisation of your project. These prompts, and some example answers are illustrated here:
$ 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)): [email protected]
[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
The Options section below provides more details on these options, default values (if applicable), what they mean, and what they affect.
Running the cookiecutter will the above responses will generate the following output skeleton, (as well as initialise a git repository example-repository, make an initial commit, and add a “0.0.0” tag to set the initial version):
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
This may seem quite daunting at first glance, but not every file is strictly necessary/one that you need to worry about. The following sections on Preparing and customising your project will address relevant files as the come up. See also Files Overview for an overview of these files.
Options
This section goes into the options you can choose in the cookiecutter, what they mean, and what they affect. If there are default values, they are explained.
project_name
This is the name of the project you would use when writing about it in the documentation. This can be anything, e.g. have spaces and hyphens.
repo_name
This is the name of the directory containing
the package. It cannot contain spaces.
This value is used to generate the URL
to the project on GitHub
(i.e. github.com/<github_host_account>/<repo_name>).
Default value: the project_name in lowercase,
with spaces and hyphens replaced with underscores.
package_name
This is the name of the module you would use when importing your package. It must follow Python module naming rules, i.e. it cannot have spaces or hyphens.
Default value: the repo_name in lowercase,
with spaces and hyphens replaced with underscores.
description
Give a short description of the project to appear in the README.
github_username
This should be your personal GitHub username. It is used for giving you credit in AUTHORS.md. github_host_account ——————-
This should be the GitHub account name used to host the
repository. In most cases, this will be the same as
the GitHub username; however, if you are creating a
package for an organisation, use the organisation
account name. This value is used to generate the URL
to the project on GitHub
(i.e. github.com/<github_host_account>/<repo_name>).
If you set this to MDAnalysis,
we will set some options for you.
For example, the default logo and favicon
will be the MDAnalysis logo and favicon.
You will also have a footer detailing our
privacy policy.
If you set this to another value, there will be entries in the documentation conf.py that use a placeholder logo and favicon.
Please see our mdanalysis-sphinx-theme documentation for more information.
Default value: the github_username.
dependency_source
This option determines which sources to use for dependencies for the package.
It affects the continuous integration testing, as well as
the dependency files written. The three choices
(conda-forge, anaconda, and pip)
are explained below.
Default value: conda-forge.
conda-forge
This option looks for dependencies first in the conda-forge channel,
then the default anaconda channel, before falling back to pip.
Note
We highly recommend using conda-forge.
conda is a great package manager for creating
isolated environments, and managing dependencies between them.
Moreover, many packages are available on conda-forge
that are not on the default anaconda channel or pip.
anaconda
This option still uses conda to manage dependencies,
but only uses the anaconda channel and pip fallback.
This option would install MDAnalysis from PyPI .
as it is not available on the default anaconda channel.
pip
This option only installs packages from PyPI.
include_ReadTheDocs
This option determines whether to include
ReadTheDocs configuration (readthedocs.yaml)
in the package. It does not affect the documentation itself.
We recommend keeping ReadTheDocs, as it is a standard and easy way
to automatically build documentation online.
Default value: “y” (True)
template_analysis_class
This option triggers the building of a skeleton custom analysis class, and associated tests. If a class name is given, it is used as the name of the analysis class. If it is not given, this step is skipped.
We strongly encourage using this option if you are planning to write custom analysis, as it copies a helpful template with comments and notes to modify.
Default value: skip