Cookiecutter for Computational Molecular Sciences Python Packages¶
These docs are are mainly a recreation of the package’s
README.md file as an example of building the docs.
Feel free to borrow from this example and consider splitting the docs into multiple pages!
A cookiecutter template for those interested in developing computational molecular sciences packages in Python. Skeletal starting repositories can be created from this template to create the file structure semi-autonomously so you can focus on what’s important: the science!
The skeletal structure is designed to help you get started, but do not feel limited by the skeleton’s features included here. Just to name a few things you can alter to suite your needs: change continuous integration options, remove deployment platforms, or test with a different suite.
- Python-centric skeletal structure with initial module files
setup.pyfor installation and packaging
- Pre-configured Window, Linux, and OSX continuous integration on GitHub Actions
- Choice of dependency locations through
- Basic testing structure with PyTest
gitinitialization + tag
- GitHub Hooks
- Automatic package version control with Versioneer
- Sample data inclusion with packaging instructions
- Basic documentation structure powered by Sphinx
- Automatic license file inclusion from several common Open Source licenses (optional)
With cookiecutter installed, execute the following command inside the folder you want to create the skeletal repository.
Which fetches this repository from github automatically and prompts the user for some simple information such as package name, author(s), and licences.
Next steps and web integrations¶
The repository contains a number of “hooks” that integrate with a variety of web services. To fully integrate the project with these web services and to get started developing your project please proceed through the following directions.
For development work it is often recommended to do a “local” python install via
pip install -e ..
This command will insert your
new project into your Python site-packages folder so that it can be found in any directory on your computer.
Setting up with GitHub¶
Upon creation, this project will initialize the output as a
git repository compatible with
Versioneer. However, this does not automatically register the
repository with GitHub. To do this, follow the instructions for
Adding an existing project to GitHub using the command line.
Follow the first step to create the repository on GitHub, but ignore the warnings about the README, license, and
.gitignore files as this repo creates them. From there, you can skip to after the “first commit” instructions and
proceed from there.
The Python testing framework was chosen to be pytest for this project. Other testing frameworks are available;
however, the authors believe the combination of easy parametrization of tests,
fixtures, and test marking
pytest particularly well suited for molecular software packages.
To get started additional tests can be added to the
project/tests/ folder. Any function starting with
test_* will automatically be
included in the testing framework. While these can be added in anywhere in your directory structure, it is highly recommended to keep them
contained within the
Tests can be run with the
pytest -v command. There are a number of additional command line arguments to
As of version 1.3, we provide preconfigured workflows for [GitHub Actions](https://github.com/features/actions), with support for Linux, MacOS and Windows. Conda support is possible thanks to the excellent [@conda-incubator’s setup-miniconda action](https://github.com/conda-incubator/setup-miniconda). We encourage you read its documentation for further details on GitHub Actions themselves.
Testing is accomplished with GitHub Actions for Linux, Windows, and macOS testing. This framework is chosen as it is completely free for open source projects and allow you to automatically verify that your project works under a variety of OS’s and Python versions; all within the existing GitHub Framework. To begin please, ensure GitHub Actions are enabled for your repository in its main settings area. This is often on by default, so there may not need to be any additional steps needed. You will also want to correct the badges which appear on the output README file to point to the correct links
Make a ReadTheDocs account and turn on the git hook. Although you can manually make the
documentation yourself through Sphinx, you can also
configure ReadTheDocs to automatically build and
publish the documentation for you. The initial skeleton of the documentation can be found in the
of your output.
Additional Python Settings in
This Cookiecutter generates the package, but there are a several package-specific Python settings you can tune to your
package’s installation needs. These are settings in the
setup.py file which contains instructions for Python on
how to install your package. Each of the options in the file are commented with what it does and when it should be
Why is Python 2.X not on the supported versions?¶
New projects generally should not be built with Python 2.7 support in mind, see the Python 3 Statement. Although the final Python 2.7 release was supported through 2020 and is the default on many legacy systems, Python 3 has been released for almost a decade and projects long term usage should not be shacked by legacy methods that will have to be replaced in very short order as Python 2 support is retired.
Directory structure template based on recommendation from the Chodera Lab’s Software Development Guidelines.
Original hosting of repository owned by the Chodera Lab