Skip to content

Latest commit

 

History

History
121 lines (86 loc) · 4.35 KB

CONTRIBUTING.md

File metadata and controls

121 lines (86 loc) · 4.35 KB

Contributing

Installation and Development

Clone from github:

git clone [email protected]:CitrineInformatics/piperoni

Create a virtual environment using Python >= 3.7. One option is to use conda, but it is not required.

conda create -n <environment_name> python=3.7
conda activate <environment_name>

Then install requirements.

pip install -U -r requirements.txt
pip install -U -r test_requirements.txt
pip install --no-deps -e .

Changes to piperoni must pass all tests, follow style guidelines, and maintain 100% test coverage. We use black as a linter. To run the linter on the "piperoni/" directory:

black piperoni/

Running tests

We use pytest to run tests and use the associated library pytest-cov to check coverage. See the PyTest documentation for more information.

Command line

To run all tests and output a report of the coverage of the "src/" directory:

pytest piperoni/

Dependencies

Dependencies are tracked in multiple places:

  • requirements files (requirements.txt)
  • setup.py

The setup.py file only contains libraries that are necessary for users to run piperoni. If you add a dependency that is necessary to run the repo, it is crucial that you add it to setup.py. You can read more about install requirements versus requirements here.

Coding Style

The piperoni library follows PEP8.

Type hints are strongly encouraged.

Positional arguments are strongly discouraged for methods with multiple arguments. Any positional argument should be required.

Docstrings must follow Numpy style so that Sphinx can parse them to make the docs.

For additional (non-binding) inspiration, check out the Google Python Style Guide.

PR Submission

Features should be developed in a branch with a descriptive name and the pull request (PR) submitted into the develop branch. Every PR to develop should increment the version number following semantic versioning. In order to be merged, a PR must be approved by one authorized user and the build must pass. A passing build requires the following:

  • All tests pass
  • The linter finds no violations of PEP8 style

Documentation

The documentation for piperoni can be found here. This documentaion is automatically generated upon a merge with main.

Building Documentation

To build the documentation for this project, make sure you've installed all dependencies (core and development) using pipenv. Once done:

cd docs/
make html

You can see the result by opening docs/_build/html/index.html in a web browser.

Autogenerated Docs

Sphinx supports generating documentation from docstrings, which is accomplished automatically during the build step using sphinxcontrib-apidoc. The output of this process is stored in the gitignore'd docs/source/reference directory. It's not stored in source control because it's generated from the current state of the docstrings in the source code.

Custom documentation

One of the outstanding features of sphinx is its support for arbitrarily organized documentation materials such as tutorials, introductions, and other context providing content. These items should be stored in source control under the docs/source directory in properly formatted .rst files.

Deployment

Travis is configured to deploy the main branch to PyPI and Github Pages.