From d167a08b6a46449eba3df3349fb458d939e8c147 Mon Sep 17 00:00:00 2001 From: John Huddleston Date: Thu, 13 Aug 2020 15:59:47 -0700 Subject: [PATCH 1/3] Update installation guide for conda Promotes conda installation to the first recommended approach, making these docs consistent with the messaging from the Nextstrain installation docs where conda is also the preferred approach. Updates the specific conda installation instructions to use the augur package from Bioconda instead of a local environment YAML file that users would have to get from the git repository first. These new instructions also recommend using mamba as a replacement for the conda installation, since the Bioconda package relies on conda-forge and installation from conda-forge with conda is notoriously slow. --- docs/installation/installation.md | 37 ++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/docs/installation/installation.md b/docs/installation/installation.md index 806b09e0a..c963ab713 100644 --- a/docs/installation/installation.md +++ b/docs/installation/installation.md @@ -1,12 +1,35 @@ # Installation +* [Using conda](#using-conda) * [Using pip from PyPi](#using-pip-from-pypi) -* [Using Conda](#using-conda) * [Install from source](#install-from-source) * [Testing if it worked](#testing-if-it-worked) --- +## Using conda + +Install [Miniconda](https://docs.conda.io/en/latest/miniconda.html). +Create a conda environment to install augur into and activate that environment. + +```bash +conda create -n nextstrain +conda activate nextstrain +``` + +Install augur and its dependencies into your environment. + +```bash +conda install -c conda-forge -c bioconda augur +``` + +For a much faster installation process, use [mamba](https://github.com/TheSnakePit/mamba) as a drop-in replacement for conda. + +```bash +conda install -c conda-forge mamba +mamba install -c conda-forge -c bioconda augur +``` + ## Using pip from PyPi Augur is written in Python 3 and requires at least Python 3.6. @@ -41,18 +64,6 @@ On Debian/Ubuntu, you can install them via: Other Linux distributions will likely have the same packages available, although the names may differ slightly. Follow [Snakemake's installation instructions](https://snakemake.readthedocs.io/en/stable/getting_started/installation.html) for your operating system. -## Using Conda - -Alternatively, augur itself and all of its dependencies can be installed into a [Conda](https://conda.io/miniconda.html) environment: - - conda env create -f environment.yml - -> _By default this environment is named "augur" but you can change that by providing a name to the above command with `-n `_ - -When that finishes, the enviroment needs to be activated whenever you want to use augur: - - conda activate augur - ## Install from source ```bash From 062fad49c87906fb4a9d4be208e171e12d939e06 Mon Sep 17 00:00:00 2001 From: John Huddleston Date: Thu, 13 Aug 2020 16:03:24 -0700 Subject: [PATCH 2/3] Update dev docs to describe Bioconda package maintanence Adds a new section next to the "Releasing" section that describes how the Bioconda releases work and how developers can update the augur conda environment through Bioconda's contribution workflow. --- DEV_DOCS.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/DEV_DOCS.md b/DEV_DOCS.md index 36e2eba5f..aae603cd7 100644 --- a/DEV_DOCS.md +++ b/DEV_DOCS.md @@ -6,7 +6,8 @@ Thank you for helping us to improve Nextstrain! This document describes: - Contributing code - Running local code changes - Testing - - Creating a release + - Releasing + - Maintaining Bioconda package - Continuous integration - Contributing documentation - Formats (Markdown and reStructuredText) @@ -170,6 +171,16 @@ If any tests fail, run the `./devel/rewind-release` script to undo the release, [a PyPi account]: https://pypi.org/account/register/ [twine]: https://pypi.org/project/twine +### Maintaining Bioconda package + +Bioconda hosts [augur’s conda package](http://bioconda.github.io/recipes/augur/README.html) and defines augur’s dependencies in [a conda recipe YAML file](https://github.com/bioconda/bioconda-recipes/blob/master/recipes/augur/meta.yaml). +New releases on GitHub automatically trigger a new Bioconda release. + +To modify augur’s dependencies or other aspects of its conda environment, [follow Bioconda’s contributing guide](https://bioconda.github.io/contributor/index.html). +You will need to update the existing recipe YAML locally and create a pull request on GitHub for testing and review. +Add your GitHub username to the `recipe_maintainers` list, if this is your first time modifying the augur recipe. +After a successful pull request review, Bioconda will automatically update the augur package that users download. + ### Travis CI Branches and PRs are tested by Travis CI jobs configured in `.travis.yml`. From 3752ba3b82765e0269aa801a227c53496d38a0bc Mon Sep 17 00:00:00 2001 From: John Huddleston Date: Thu, 13 Aug 2020 16:04:23 -0700 Subject: [PATCH 3/3] Add a badge for installation from Bioconda Surfaces augur's existing Bioconda package through a fancy badge. --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 4d61e6cf9..db07ecc3e 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ [![Build Status](https://travis-ci.com/nextstrain/augur.svg?branch=master)](https://travis-ci.com/nextstrain/augur) [![PyPI version](https://badge.fury.io/py/nextstrain-augur.svg)](https://pypi.org/project/nextstrain-augur/) +[![install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](http://bioconda.github.io/recipes/augur/README.html) [![Documentation Status](https://readthedocs.org/projects/nextstrain-augur/badge/?version=latest)](https://nextstrain-augur.readthedocs.io/en/stable/?badge=latest) [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)