Thank you for helping us to improve Nextstrain! This document describes:
- Getting Started
- Contributing code
- Running local code changes
- Testing
- Creating a release
- Continuous integration
- Contributing documentation
- Formats (Markdown and reStructuredText)
- Documentation structure
- Building documentation
To be an effective, productive contributor, please start by reading the Nextstrain contributing guide for useful information about how to pick an issue, submit your contributions, and so on.
This project strictly adheres to the Contributor Covenant Code of Conduct.
Please see the project board for currently available issues.
We currently target compatibility with Python 3.4 and higher. As Python releases new versions, the minimum target compatibility may be increased in the future.
Versions for this project, Augur, from 3.0.0 onwards aim to follow the Semantic Versioning rules.
While you are making code changes, you will want to run augur to see it behavior with those changes. To to test your local changes (without installing them to your system), run the following convenience script from the root of your cloned git repository:
./bin/augur
Note that the ./bin/augur
convenience script is not installing augur
system-wide with pip.
As an alternative to using the convenience script, you can install augur from source
as an editable package so that your global augur
command always uses your
local source code copy:
pip install -e .[dev]
Using an "editable package" is not recommended if you want to be able to compare output
from a stable, released version of augur with your development version (e.g. comparing
output of augur
installed with pip and ./bin/augur
from your local source code).
Writing good tests and running tests helps maintain code quality and eases future refactoring. We use the pytest package for running our tests. This section will describe briefly:
- Writing tests
- Unit tests
- Doctests
- Running tests
- Locally
- Continuous Integration
It's good practice to write unit tests for any code contribution. The
pytest documentation and Python documentation
are good references for unit tests. Augur's unit tests are located in the tests
directory and
there is generally one test file for each code file.
On the other hand, doctests are a type of tests that are written within a module's docstrings. They can be helpful for testing a real-world example and determining if a regression is introduced in a particular module.
A pull request should always contain unit tests. Optionally, a pull request may also contain doctests if the contributor believes a doctest would improve the documentation and execution of a real world example.
You've written tests and now you want to run them to see if they are passing. To run augur's tests (unit tests and doctests) with pytest and Python3, use the following command from the root, top-level of the augur repository:
pytest -c pytest.python3.ini
If you are running legacy augur code using Python 2, execute pytest -c pytest.python2.ini
.
Troubleshooting tip: As tests run on the development code in the augur repository, your environment should not have an existing augur installation that could cause a conflict in pytest.
We also use Continuous integration with Travis CI to run tests on every pull request submitted to the project.
New releases are tagged in git using an "annotated" tag. If the git option
user.signingKey
is set, the tag will also be signed. Signed tags are
preferred, but it can be hard to setup GPG correctly. The release
branch
should always point to the latest release tag. Source and wheel (binary)
distributions are uploaded to the nextstrain-augur project on
PyPi.
There is a ./devel/release
script which will prepare a new release from your
local repository. It ends with instructions for you on how to push the release
commit/tag/branch and how to upload the built distributions to PyPi. You'll
need a PyPi account and twine installed to do the latter.
Branches and PRs are tested by Travis CI jobs configured in .travis.yml
.
New releases, via pushes to the release
branch, trigger a new docker-base
build to keep the Docker image up-to-date.
Documentation is built using Sphinx and hosted on Read The Docs. Versions of the documentation for each augur release and git branch are available and preserved. Read The Docs is updated automatically from commits and releases on GitHub.
Documentation is mostly written as reStructuredText (.rst) files, but they can also be Markdown (.md) files. There are advantages to both formats:
- reStructuredText enables python-generated text to fill your documentation as in the
auto-importing of modules or usage of plugins like
sphinx-argparse
(see below). - Markdown is more intuitive to write and is widely used outside of python development.
- If you don't need autogeneration of help documentation, then you may want to stick with writing Markdown.
Sphinx, coupled with reStructuredText, can be tricky to learn. Here's a subset of reStructuredText worth committing to memory to help you get started writing these files.
Many Sphinx reStructuredText files contain a directive to add relations between single files in the documentation known as a Table of Contents Tree (TOC Tree).
Human-readable augur and augur subcommand documentation is written using a Sphinx extension called sphinx-argparse.
The documentation source-files are located in ./docs
, with ./docs/index.rst
being the main entry point.
Each subsection of the documentation is a subdirectory inside ./docs
.
For instance, the tutorials are all found in ./docs/tutorials
and are included in the documentation website via the directive in ./docs/index.rst
.
Building the documentation locally is useful to test changes. First, make sure you have the development dependencies of augur installed:
pip install -e .[dev]
This installs packages listed in the dev
section of extras_require
in setup.py,
as well as augur's dependencies as necessary.
Sphinx and make are used when building documentation. Here are some examples that you may find useful:
Build the HTML output format by running:
make -C docs html
Sphinx can build other formats, such as epub. To see other available formats, run:
make -C docs help
To update the API documentation after adding or removing an augur submodule, autogenerate a new API file as follows.
sphinx-apidoc -T -f -MeT -o docs/api augur
To make doc rebuilds faster, Sphinx caches built documentation by default, which is generally great, but can cause the sidebar of pages to be stale. You can clean out the cache with:
make -C docs clean
To view the generated documentation in your browser, Mac users should run:
open docs/_build/html/index.html
Linux users can view the docs by running:
xdg-open docs/_build/html/index.html
This will open your browser for you to see and read your work.