This document describes how to edit the package, run the tests, build the docs, put tagged versions on PyPI, etc.
- Package code is in pdb_prot_align
- Docs are in docs
- Jupyter notebooks are in notebooks
- Unit tests are in tests
To make changes to the code, you should make a branch or fork, make your changes, and then submit a pull request. If you aren't sure about pull requests:
- A general description of pull requests: https://help.github.com/en/articles/about-pull-requests
- How to create a pull request: https://help.github.com/en/articles/creating-a-pull-request
- How to structure your pull requests (one conceptually distinct change per pull request): https://medium.com/@fagnerbrack/one-pull-request-one-concern-e84a27dfe9f1
You should document your code clearly with numpy style documentation. You may also want to write sphinx documentation / examples in docs or the notebooks to demonstrate large-scale functionality.
You should add tests. For simple things, these can be doctests in the code. For more elaborate functionality, put unit tests in tests. Note also that the Jupyter notebooks in notebooks are tested via nbval. If you are getting errors on these notebook tests due to testing cells that output objects that can't be properly tested (such as widgets), see the nbval-ignore-output tag option discussed in the nbval docs.
The version is single sourced in __init__.py.
When modifying a tagged version (e.g., 0.1.0), indicate you are working on a development version by adding a dev (e.g., 0.1.dev1).
See here for more information on version numbers.
Conceptual descriptions of changes should also be tracked in the CHANGELOG.
When you add code that uses a new package that is not in the standard python library, you should add it to the dependencies specified under the install_requires option in setup.py. See here for information on how to do this, and how to specify minimal required versions. As described in the above link, you should not pin exact versions in install_requires in setup.py unless absolutely necessary.
The Jupyter notebooks in notebooks can be run interactively on mybinder by going to the following link: https://mybinder.org/v2/gh/jbloomlab/pdb_prot_align/master?filepath=notebooks
In order for this to work, you need to keep the environment.yml configuration file up to date with the dependencies for running these notebooks as described here. Note that unlike for the install_requires in setup.py, you may want to pin exact versions here to get reproducible installations. Look into the pip freeze and conda env export commands on how to automatically create such a configuration file.
As you add new codes, you should create tests to make sure it is working correctly. These can include:
- doctests in the code
- unit tests in the ./tests/ subdirectory
After you make changes, you should run two sets of tests. To run the tests, go to the top-level packag directory. Then make sure that you have installed the packages listed in test_requirements.txt. If these are not installed, install them with:
pip install -r test_requirements.txt
Then use flake8 to lint the code by running:
flake8
If you need to change the flake8 configuration, edit the .flake8 file.
Then run the tests with pytest by running:
pytest
If you need to change the pytest configuration, edit the pytest.ini file.
The aforementioned flake8 and pytest tests will be run automatically by the Travis continuous integration system as specified in the .travis.yml file. Note that running the Travis tests requires you to register the project with Travis.
If the tests are passing, you will see this on the Travis badge on GitHub repo main page.
You can configure Travis to provide automatic Slack notifications of the test results. To do that, follow the instructions here.
See docs/README.rst for information on how to build the documentation.
When you have a new stable release, you will want to tag it and put it on PyPI where it can be installed with pip. First, make sure the version number is up-to-date in __init__.py and the CHANGELOG. Then commit the code to GitHub if you haven't already done so. Next tag the version, as in:
git tag -a 0.1.0 -m 'version 0.1.0'
and then push the tag to GitHub with:
git push --tags
Finally, upload to PyPI with twine as described here. Note that this requires you to have registered the package on PyPI if this is the first version of the package there.