nmayhall-vt/python-package-best-practices

http://nmayhall-vt.github.io/python-package-best-practices/

Python Package Best Practices

This repository contains lessons for the MolSSI Workshop "Best Practices in Python Package Development". To complete the lessons, navigate to the lesson pages. Make sure to visit setup first to obtain lesson materials and install required software.

This workshop is designed to take place in one and a half to two days. Students begin the workshop with python code stored in a Jupyter notebook. During the workshop, we refactor and format the code into a Python package. At the end, all participants should have a repository on GitHub which implements MolSSI's Best Practices for a Python package. Depending on the level of students taking this course, all lessons may not be accomplished in two days. Workshops should cover at least lessons 1-6 (outlined below), with more potentially being added for more advanced groups.

Lessons for this module were developed using the Software Carpentry lesson template, and is itself an example of the use of that template. Please see https://carpentries.github.io/lesson-example/ for a rendered version of this material, including detailed instructions on design, setup, and formatting.

Workshop Topics

This workshop walks students through setting up, writing code, and setting up multiple services (continuous integration, codecov, etc) for a Python package. When finished, this repo will include the following topics. Items which have a checkbox are (mostly) finished, and can be followed online.

• Setting up a python package using the MolSSI Computational Molecular Sciences (CMS) CookieCutter
• Basic use of git and GitHub.
• Python coding style, docstrings.
• Code collaboration on GitHub (Fork-PR workflow)
• Unit testing using pytest.
• Continuous integration using travis-ci.
• Documentation using sphinx and readthedocs
• Deploying packages on conda-forge

Contributing to these lessons

To contribute to this lesson, fork this repository and make changes on your local clone. Once you have changes you would like incorporated, create a pull request, and we will review your contributions.

All edits to lessons should be done under _episodes in the appropriate markdown file.

General instructions from software carpentry for working with this template are given below.

Quick Instructions

1. Please read the episodes of this lesson to format your material.

2. Please keep the master copy of your lesson in your repository's gh-pages branch, since that is what is automatically published as a website by GitHub.

3. To preview material, please run make serve from the command line to launch Jekyll with the correct parameters, or push to your repository's gh-pages branch and let GitHub take care of the rendering.

4. Run make lesson-check to check that your files follow our formatting rules.

5. If you find an error or omission in this documentation, please file an issue in this repository. If you find an error or omission in the lesson template, please file an issue in the styles repository instead.

Layout

The layout of this repository is explained in this site's episodes. In brief:

1. The source for pages that appear as top-level items in the navigation bar are stored in the root directory, including the home page (index.md), the reference page (reference.md), and the setup instructions (setup.md).

2. Source files for lesson episodes are stored in _episodes; _episodes/01-xyz.md generates /01-xyz/index.html, which can be linked to using /01-xyz/.

3. Files that appear under the "extras" menu are stored in _extras.

4. Figures are stored in the fig directory, data sets in data, source code in code, and miscellaneous files in files.