Developer documentation lacks complete installation instructions

[huddlej]

Our current developer documentation (in docs/contribute/DEV_DOCS.md) lacks information about how to setup a complete development environment that includes bioinformatics tools like mafft, etc. that are required to test augur. This documentation is not prominent in the README nor is it accessible from the main RTD interface at docs.nextstrain.org.

To fix this issue, I propose that we:

• Add a new top-level heading to the README for "Contributing to Augur" after the "Quickstart" that links to the contributor's guide and the developer documentation.
• Update the developer documentation to include a full explanation of how to clone the source code, create a development environment, and install the development version of Augur.
• Expose the developer documentation through the main Augur docs as a top-level link in the table of contents above the Python API.
• Update the "Install from source" section of the Augur installation guide to link to the developer's guide. This supports the use case where a user looks for how to install Augur from source code with the intention to contribute to the project.

[jtboing]

Hello. If nobody is doing this, can this issue be assigned to me?

[tsibley]

@jtboing It's yours!

[jtboing]

Thanks! I have a question. For the second item, is there a preferred development environment? If there is none, then which one should I use an example command? or is there no need for an example here?

[huddlej]

@jtboing For now, the preferred environment can be the conda nextstrain environment plus the editable installation of Augur with pip, although it's likely other folks on our team have a different preferred approach.

# Create a new conda environment.
conda create -n augur
conda activate augur

# Install mamba, if you haven't already.
# This makes installation from conda-forge much faster.
conda install -c conda-forge mamba

# Install augur from conda with external dependencies.
mamba install -c conda-forge -c bioconda augur

# Get the latest augur source code.
git clone https://github.com/nextstrain/augur.git
cd augur

# Install augur development version on top of previously installed conda version.
python3 -m pip install -e '.[dev]'

[jameshadfield]

A potential source of confusion with the current setup is naming the (empty) conda environment nextstrain and installing augur from source into that, as we maintain a conda environment of the same name which will install augur from pip.

My advice for https://docs.nextstrain.org/projects/augur/en/stable/installation/installation.html would be 3 sections:

1. Conda via https://github.com/nextstrain/conda (will also install auspice & nextstrain-cli, and should allow one to then run augur via nextstrain build --native or augur)
2. Pip install + other necessary software, for those who want to manage their own environments
3. From source (for development purposes) suggesting a blank conda environment named augur (or nextstrain-dev etc)

[huddlej]

Those are good points, @jameshadfield. There is definitely still a lot of potential confusion. I think what you're describing is the bigger issue of providing a single (or reduced?) set of canonical installation instructions.

In the long-term, I'd like to replace the separate conda environment (and repo) with corresponding Bioconda packages. The current augur package in Bioconda gets us most of the way there by encoding all of the bioinformatics dependencies that aren't available from PyPI (mafft, etc.). The Bioconda package gets updated semi-automatically with each new Augur release, so this package always provides the latest stable version.

To get a "full Nextstrain environment" represented by the current conda repo, we need packages for auspice and the CLI. In the rough schematic in my mind, the auspice package would depend on node and the CLI package would depend on the auspice and augur packages. Then, creating the full environment could look like this:

# Install mamba, if you haven't already.
# This makes installation from conda-forge much faster.
conda install -c conda-forge mamba

# Create a new conda environment with the Nextstrain CLI and its dependencies (augur, auspice, etc.).
mamba create -n nextstrain -c conda-forge -c bioconda nextstrain-cli

# Test the environment.
conda activate nextstrain
nextstrain -h

@tsibley might have thoughts about how this breaks down in practice though.

[huddlej]

I just edited the original post to refer to an augur environment instead of nextstrain, for the dev instructions.

[jtboing]

Hello. I have made pull request #686 with the required additions. Please notify me if further changes or corrections are needed in the documentation. Thanks.