Skip to content

Commit

Permalink
Reorg README, improve findability of documentation, separate dev docs (…
Browse files Browse the repository at this point in the history 
…#461)
  • Loading branch information
@sidneymbell
sidneymbell authored Mar 24, 2020
1 parent 9d95ec7 commit 484eb5e
Show file tree
Hide file tree
Showing 2 changed files with 160 additions and 147 deletions.
133 changes: 133 additions & 0 deletions DEV_DOCS.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
# Development docs

## Getting started

Thank you for helping us to improve Nextstrain!

##### [To get started, please see the contributing guide for useful information about how to pick an issue, submit your contributions, and so on.](https://github.com/nextstrain/.github/blob/master/CONTRIBUTING.md)


This project strictly adheres to the [Contributor Covenant Code of Conduct](https://github.com/nextstrain/.github/blob/master/CODE_OF_CONDUCT.md).

Please see the [project board](https://github.com/orgs/nextstrain/projects/6) for currently available issues.

## Contributing code
We currently target compatibility with Python 3.4 and higher. This may be
increased to in the future.

Versions for this project from 3.0.0 onwards aim to follow the [Semantic
Versioning rules](https://semver.org).

### Running with local changes

From within a clone of the git repository you can run `./bin/augur` to test your local changes without installing them.
(Note that `./bin/augur` is not the script that gets installed by pip as `augur`; that script is generated by the `entry_points` configuration in `setup.py`.)

You can also 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]

This is not recommended if you want to be able to compare output from a stable version of augur to a development version (e.g. comparing output of `augur` installed with pip and `./bin/augur` from your local source code).

### Testing

Run doctests and unit tests for augur from Python 3 with pytest from the top-level of the augur repository.

pytest -c pytest.python3.ini

Or, run tests for augur from Python 2.

pytest -c pytest.python2.ini

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.

### Releasing

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](https://pypi.org/project/nextstrain-augur).

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.

[signed]: https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work
[a PyPi account]: https://pypi.org/account/register/
[twine]: https://pypi.org/project/twine

### Travis CI

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.

[docker-base]: https://github.com/nextstrain/docker-base


## Contributing documentation

[Documentation](https://nextstrain-augur.readthedocs.io) is built using [Sphinx](http://sphinx-doc.org/) and hosted on [Read The Docs](https://readthedocs.org/).
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](http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) (.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 documentaiton, 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](https://simonwillison.net/2018/Aug/25/restructuredtext/) to help you get started writing these files.


Many Sphinx reStructuredText files contain a [directive](http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html) to add relations between single files in the documentation known as a Table of Contents Tree ([TOC Tree](https://documentation.help/Sphinx/toctree.html)).

Human-readable augur and augur subcommand documentation is written using a Sphinx extension called [sphinx-argparse](https://sphinx-argparse.readthedocs.io/en/latest/index.html).


### Folder structure

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 documentation

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_, in addition to any normal augur dependencies as necessary.)


Then build the HTML output format by running:

make -C docs html

You can see other available formats by running:

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

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
174 changes: 27 additions & 147 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,41 +2,43 @@
[![PyPI version](https://badge.fury.io/py/nextstrain-augur.svg)](https://pypi.org/project/nextstrain-augur/)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)

# Introduction
## About Nextstrain

Nextstrain is an open-source project to harness the scientific and public health potential of pathogen genome data.
We provide a continually-updated view of publicly available data with powerful analytics and visualizations showing pathogen evolution and epidemic spread.
Our goal is to aid epidemiological understanding and improve outbreak response.

Resulting data and inferences are available live at the website [nextstrain.org](https://nextstrain.org).
Documentation is available at [nextstrain.org/docs](https://nextstrain.org/docs).

# Augur

## About Augur
*Definition: One held to foretell events by omens.*

Augur is the bioinformatics toolkit we use to track evolution from sequence and serological data.
It provides a collection of commands which are designed to be composable into larger processing pipelines.
Documentation for augur is available at [nextstrain.org/docs/bioinformatics](https://nextstrain.org/docs/bioinformatics).

## Installation
The output of augur is a series of JSONs that can be used to visualize your results using [Auspice](https://github.com/nextstrain/auspice).

Augur is written in Python 3 and requires at least Python 3.4.
It's published on [PyPi](https://pypi.org) as [nextstrain-augur](https://pypi.org/project/nextstrain-augur), so you can install it with `pip` (or `pip3`) like so:

pip install nextstrain-augur
## Documentation
* [Overview of how Augur fits together with other Nextstrain tools](https://nextstrain.org/docs/getting-started/introduction#open-source-tools-for-the-community)
* [Overview of Augur usage](https://nextstrain.org/docs/bioinformatics/introduction-to-augur)
* [Technical documentation for Augur](https://nextstrain-augur.readthedocs.io/en/stable/installation/installation.html)
* [Contributor guide](https://github.com/nextstrain/.github/blob/master/CONTRIBUTING.md)
* [Project board with available issues](https://github.com/orgs/nextstrain/projects/6)
* [Developer docs for Augur](./DEV_DOCS.md)

You can also install from a git clone or other copy of the source code by running:

pip install .

If your system has both Python 2 and Python 3 installed side-by-side, you may need to use `pip3` or `python3 -m pip` instead of just `pip` (which often defaults to Python 2 when both Python versions are installed).
# Quickstart

This install depends on a fairly minimal set of external Python libraries. There are some
functions in augur that require a larger set of dependencies. These can be installed via:
## Installation

pip install .[full]
Augur is written in Python 3 and requires at least Python 3.4.

To install, run:
```bash
pip install nextstrain-augur[full]
```

Augur uses some common external bioinformatics programs which you'll need to install to have a fully functioning toolkit:

Expand All @@ -49,15 +51,20 @@ Augur uses some common external bioinformatics programs which you'll need to ins

* Bacterial data (or any VCF usage) requires [vcftools](https://vcftools.github.io/)

Alternatively, all these dependencies (as well as augur itself) can be installed via Conda by running:
On macOS, you can install these external programs using Homebrew with:
```bash
brew install mafft iqtree raxml fasttree vcftools
```

conda env create -f environment.yml
On Debian/Ubuntu, you can install them via:

Once installed, Conda the enviroment need to be activated whenever augur is to be used, by running:
```bash
sudo apt install mafft iqtree raxml fasttree vcftools
```

conda activate augur
[For more extensive installation instructions, please see the technical docs](https://nextstrain-augur.readthedocs.io/en/stable/installation/installation.html)

## Usage
## Basic Usage

All of Augur's commands are accessed through the `augur` program.
For example, to infer ancestral sequences from a tree, you'd run `augur ancestral`.
Expand Down Expand Up @@ -101,133 +108,6 @@ optional arguments:
For more information on a specific command, you can run it with the `--help` option, for example, `augur tree --help`.


## Development

Development of `augur` happens at <https://github.com/nextstrain/augur>.

We currently target compatibility with Python 3.4 and higher. This may be
increased to in the future.

Versions for this project from 3.0.0 onwards aim to follow the [Semantic
Versioning rules](https://semver.org).

### Running with local changes

From within a clone of the git repository you can run `./bin/augur` to test your local changes without installing them.
(Note that `./bin/augur` is not the script that gets installed by pip as `augur`; that script is generated by the `entry_points` configuration in `setup.py`.)

You can also 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]

This is not recommended if you want to be able to compare output from a stable version of augur to a development version (e.g. comparing output of `augur` installed with pip and `./bin/augur` from your local source code).

### Testing

Run doctests and unit tests for augur from Python 3 with pytest from the top-level of the augur repository.

pytest -c pytest.python3.ini

Or, run tests for augur from Python 2.

pytest -c pytest.python2.ini

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.

### Releasing

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](https://pypi.org/project/nextstrain-augur).

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.

[signed]: https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work
[a PyPi account]: https://pypi.org/account/register/
[twine]: https://pypi.org/project/twine

### Travis CI

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.

[docker-base]: https://github.com/nextstrain/docker-base


## Documentation


[Documentation](https://nextstrain-augur.readthedocs.io) is built using [Sphinx](http://sphinx-doc.org/) and hosted on [Read The Docs](https://readthedocs.org/).
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](http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) (.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 documentaiton, 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](https://simonwillison.net/2018/Aug/25/restructuredtext/) to help you get started writing these files.


Many Sphinx reStructuredText files contain a [directive](http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html) to add relations between single files in the documentation known as a Table of Contents Tree ([TOC Tree](https://documentation.help/Sphinx/toctree.html)).

Human-readable augur and augur subcommand documentation is written using a Sphinx extension called [sphinx-argparse](https://sphinx-argparse.readthedocs.io/en/latest/index.html).


### Folder structure

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 documentation

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_, in addition to any normal augur dependencies as necessary.)


Then build the HTML output format by running:

make -C docs html

You can see other available formats by running:

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

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



## License and copyright

Copyright 2014-2019 Trevor Bedford and Richard Neher.
Expand Down

0 comments on commit 484eb5e

Please sign in to comment.