Update install docs #157
Update install docs #157
Conversation
New users are more likely to want to interface with augur via an interactive shell than a Snakemake workflow, so it makes sense to show how to do that at the end of installation.
victorlin
force-pushed
the
victorlin/update-install-docs
branch
4 times, most recently
from
a651379
to
675e98d
Compare
| Why do I get an error when installing to my Conda environment on a Mac computer with Apple silicon (e.g. M1)? | ||
| ------------------------------------------------------------------------------------------------------------- |
There was a problem hiding this comment.
I thought about this some more and came up with nextstrain/bioconda-recipes#3.
There was a problem hiding this comment.
Also +1 for this direction.
My feeling is that our docs (and perhaps software) need to make it clearer what runtime one is using. It's implicit in many of these pages that one knows the answer to that question. In that linked slack thread Tom says "I've been wanting to more fully document and compare/contrast the runtimes for a bit" so perhaps it's better to not tackle this too much in this PR.
|
|
||
| When completed, you'll be ready to run Nextstrain :term:`workflows <workflow>`. | ||
|
|
||
|
|
There was a problem hiding this comment.
I'd add a link up here (as well as at the bottom of the page) linking out to "Manage installation" -- the two pages are somewhat separated in the sidebar and I presume many people would come to this page first.
There was a problem hiding this comment.
There is already a link at the bottom of the page, and I've moved the table of contents a little lower (force-push). It has a link to the section which links to the "manage installation" page, which I think is sufficient.
I don't love it, but the placement of the "Manage installation" page in the sidebar is the best I could think of. Let me know if you have a better suggestion.
There was a problem hiding this comment.
Thanks!
I don't love it, but the placement of the "Manage installation" page in the sidebar is the best I could think of. Let me know if you have a better suggestion.
I don't think there's a perfect way to order the sidebar. At least, I've never found one.
There was a problem hiding this comment.
+1 with the changes @jameshadfield asked for, with which I concur.
victorlin
force-pushed
the
victorlin/update-install-docs
branch
2 times, most recently
from
427b38c
to
4366c1b
Compare
This keeps the installation page to a minimum, so new users will not be inclined to skip over anything. Also, improve the sectioning on the installation page and add table of contents to both pages.
This is an opinionated change, but should better help users decide which runtime to use. With the increased maturity of managed runtimes, the ambient runtime is now at a place where it should only be used by people familiar with managing their own Conda environments. Notable changes: - Add a note that familiarity with Conda is a prerequisite to the example ambient runtime setup steps. - Remove Miniconda and Mamba setup instructions. - Update all "custom Conda environment" references to be generic for any Conda environment. - Repurpose an FAQ entry around limitations of emulation on Apple silicon. I'm hopeful that users who have previously followed the ambient/native runtime setup instructions have gained enough Conda familiarity to know that "nextstrain" is the name of their custom Conda environment, so they can continue to reference the newer installation docs for other installation-related instructions.
victorlin
force-pushed
the
victorlin/update-install-docs
branch
from
4366c1b
to
bb94772
Compare
Description of proposed changes
Updating the installation docs given recent runtime improvements. See commit messages.
Previews:
Related issue(s)
Testing