karr_lab_build_utils documentation

This package performs several aspects of the Karr Lab’s build system:

• Versioning with Git and GitHub
  • Creates new Git repositories with the proper directory structure and files for our build system
• Testing code with Python 2 and 3
  • Uses pytest or nose test runners
  • Uses coverage or instrumental for statement, branch, or multiple condition coverage analysis
  • Runs the tests locally or using a Docker image or the CircleCI local executor
• Static code analysis with Pylint
  • Statistically analyzes code using Pylint
• Documentation with Sphinx
  • Generates documentation using Sphinx
• Dependency management
  • Installs and upgrades all of the requirements of a package
  • Identifies missing and unused dependencies
  • Compiles downstream package dependencies
  • Visualizes downstream packages dependencies
  • Checks for cycles in package dependencies
• Continuous integration with CircleCI
  • Creates CircleCI builds for packages
  • Gets, sets, and deletes environment variables
  • Triggers CircleCI to test downstream dependencies
  • Manages passwords used in CircleCI
  • Email notifications
• Test analysis with our test history server
  • Uploads test reports to our test history server
• Coverage analysis with Coveralls
  • Uploads coverage reports to Coveralls
• Coverage analysis and static code analysis with Code Climate
  • Create Code Climate builds for packages
  • Uploads coverage reports to Code Climate
• Distribution with PyPI
  • Uploads packages to PyPI

The build system is primarily designed for:

• Code that is implemented with Python 2/3
• Tests that can be run with pytest
• Code that is documented with Sphinx in Napolean/Google style
• Code that is versioned with Git/GitHub
• Builds that are run on CircleCI
• Coverage reports that are hosted on Coveralls and Code Climate
• Documentation that is hosted on Read the Docs

Contents

• 1. Installation
  • 1.1. Pre-requisites
  • 1.2. Install the latest revision from GitHub
• 2. Tutorial for WC modeling software developers
  • 2.1. Creating a new package
  • 2.2. Developing a package
  • 2.3. Managing dependencies of packages
    • 2.3.1. Installing the dependencies for a package
    • 2.3.2. Finding missing requirements for a package
    • 2.3.3. Finding unused requirements for a package
    • 2.3.4. Compiling the downstream dependencies of a package
  • 2.4. Configuring packages
  • 2.5. Testing with pytest, coverage, instrumental, Docker, and CircleCI
    • 2.5.1. Running the tests for a package
    • 2.5.2. Evaluating the coverage of the tests
    • 2.5.3. Running tests with Docker or the CircleCI local executor
  • 2.6. Configuring tests of downstream dependencies
  • 2.7. Configuring the static analyses run by the build system
  • 2.8. Configuring build email notifications
  • 2.9. Documenting code with Sphinx
    • 2.9.1. Building the documentation for a package
    • 2.9.2. Spell checking documentation
• 3. Tutorial for build administrators
  • 3.1. Getting help
  • 3.2. Versioning with Git and GitHub
    • 3.2.1. Creating a repository for a package
  • 3.3. Statically analyzing code with Pylint
    • 3.3.1. Statically analyzing a package with Pylint
    • 3.3.2. Visualizing all of the package dependencies
  • 3.4. Continuous integration with CircleCI
    • 3.4.1. Following a build for a package
    • 3.4.2. Getting the environment variables for a package
    • 3.4.3. Setting a environment variable for a package
    • 3.4.4. Deleting a environment variable for a package
    • 3.4.5. Triggering testing downstream dependencies of a package
  • 3.5. Statically analyzing code and performing coverage analysis with Code Climate
    • 3.5.1. Creating a Code Climate build for a package
  • 3.6. Distributing packages with PyPI
    • 3.6.1. Distributing a package by uploading it to PyPI
• 4. About
  • 4.1. License
  • 4.2. Development team
  • 4.3. Acknowledgments
  • 4.4. Questions and comments