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. API documentation
  • 4.1. karr_lab_build_utils package
    • 4.1.1. Subpackages
    • 4.1.2. Submodules
    • 4.1.3. karr_lab_build_utils.__main__ module
    • 4.1.4. karr_lab_build_utils._version module
    • 4.1.5. karr_lab_build_utils.core module
    • 4.1.6. Module contents
• 5. About
  • 5.1. License
  • 5.2. Development team
  • 5.3. Acknowledgments
  • 5.4. Questions and comments