Bootstrap a Scientific Python Library

This is a tutorial with a template for packaging, testing, documenting, and publishing scientific Python code.

Do you have a folder of disorganized scientific Python scripts? Are you always hunting for code snippets scattered across dozens of Jupyter notebooks? Has it become unwieldy to manage, update, and share with collaborators? This tutorial is for you.

See this lightning talk from Scipy 2018 for a short overview of the motivation for and scope of this tutorial.

Starting from a working, full-featured template, you will:

• Move your code into a version-controlled, installable Python package.

• Share your code on GitHub.

• Generate documentation including interactive usage examples and plots.

• Add automated tests to help ensure that new changes don’t break existing functionality.

• Use a free CI (continuous integration) service to automatically run your tests against any proposed changes and automatically publish the latest documentation when a change is made.

• Publish a release on PyPI so that users and collaborators can install your code with pip.

• Philosophy of this Tutorial
  • The Tools, and the Problems They Solve
• Getting Started
• The Code Itself
  • A simple function with inline documentation
  • Update Requirements
  • Try it
  • Run the Tests
  • Write a Test
  • “Lint”: Check for suspicious-looking code
  • Commit and Push Changes
  • Multiple modules
• Guiding Design Principles
  • Collaborate
  • Don’t Be Afraid to Refactor
  • Prefer “Wide” over “Deep”
  • Keep I/O Separate
  • Duck Typing is a Good Idea
  • “Stop Writing Classes”
  • Permissiveness Isn’t Always Convenient
  • Write Useful Error Messages
  • Write for Readability
  • Complexity is Always Conserved
• Continous Integration Testing
  • What is CI for?
  • Travis-CI Configuration
  • Activate Travis-CI for Your GitHub Repository
• Git hooks and pre-commit
  • What are git hooks for?
  • It’s just formatting, who cares?
  • Configuring pre-commit
  • Hooks included in this cookiecutter
  • Committing Changes
• Writing Documentation
  • Build the docs
  • Update the docs
  • API Documentation
  • Narrative Documentation
• Including Data Files
  • Consider Alternatives
  • How to Package Data Files
• Publishing the Documentation
  • Configure Doctr
  • Alternatives
• Publishing Releases
• Common Patterns for Tests
  • Parametrized Tests
  • Fixtures
  • Skipping Tests
• Environments and Package Managers
  • Conda
• Futher Reading
  • Other Tutorials and Articles
  • Other Python Cookiecutters
  • Basics