Contributing to mokapot

First off, thanks you for taking the time to contribute.

The following document provides guidelines for contributing to the documentation and the code of mokapot. No contribution is too small! Even fixing a simple typo in the documentation is immensely helpful.

Contributing to the documentation

We use sphinx to generate our documentation and deploy it to this site. Most of the pages on the site are created from simple text files written in the reStructuredText markup language. There are two exceptions to this:

The API and command line documentation are automatically generated from the documentation contained in the code.
The Vignettes are created from Jupyter notebooks.

Editing most documents

The easiest way to edit a document is by clicking the “Edit on GitHub” like in the top right hand corner of each page. You’ll then be taken to GitHub where to you can click the pencil to edit the document:

Click the edit button in the upper right corner.

You can then make your changes directly on GitHub. Once you’re finished fill in a description of what you changed and click the “Propose Changes” button.

Alternatively, these documents live in the docs/source directory of the repository and can be edited like code. See Contributing to the code below for more details on contributing this way.

Editing the Vignettes

Depending on what needs to change, there are two paths to updating the vignettes:

If only the text needs to be changed: Click the “View page source” button at the top left corner of the vignette you want to edit. Then follow the steps under Editing most documents above. Note that, because these are Jupyter notebooks and not flat text files, they will be more difficult to look through.
If the code needs to be changed: This modification needs to be done similarly as editing the mokapot source code (see Contributing to the code). Briefly, you’ll need to clone the repository from GitHub then navigate to docs/source/vignettes. You then need to start-up the Jupyter notebook for the vignette you wish to edit and make your change. After making your change, make sure to restart the notebook and run all cells. After this has been completed, save the notebook and commit the edited version to the repository. Be sure to explicitly detail the change you made when submitting your pull request.

Contributing to the code

We welcome contributions to the source code of mokapot—particularly ones that address discussed issues.

Contributions to mokapot follow a standard GitHub contribution workflow:

Create your own fork of the mokapot repository on GitHub.
Clone your forked mokapot repository to work on locally.
Create a new branch with a descriptive name for your changes:
```
git checkout -b fix_x
```
Make your changes (make sure to read below first!).
Add, commit, and push your changes to your forked repository.
On the GitHub page for you forked repository, click “Pull request” to propose adding your changes to mokapot.
We’ll review, discuss, and help you make any revisions that are required. If all goes well, your changes will be added to mokapot in the next release!

Python code style

The mokapot project follows the PEP 8 guidelines for Python code style. More specifically, we use black to format code and lint Python code in mokapot.

We highly recommend setting up a pre-commit hook for black. This will run black on all of the Python source files before the changes can be committed. Because we run black for code linting as part of our tests, setting up this hook can save you from having to revise code formatting. Take the following steps to set up the pre-commit hook:

Verify that black and pre-commit are installed. If not, you can install them with pip or conda:

# Using pip
pip install black pre-commit

# Using conda
conda -c conda-forge black pre-commit

Navigate to your local copy of the mokapot repository and activate the hook:
```
pre-commit install
```

One the hook is installed, black will be run before any commit is made. If a file is changed by black, then you need to git add the file again before finished the commit.