From c5eeb8ac9da156a3ddf808580d29178f5c41fb75 Mon Sep 17 00:00:00 2001 From: eharkins Date: Wed, 30 Sep 2020 15:28:43 -0400 Subject: [PATCH 01/16] add link back to parent project for api docs --- docs/api/api.rst | 3 +++ docs/conf.py | 8 +++++++- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/api/api.rst b/docs/api/api.rst index c89729232..a93d2cde7 100644 --- a/docs/api/api.rst +++ b/docs/api/api.rst @@ -2,6 +2,9 @@ Python Development API ====================== +.. warning:: + This is the augur API reference documentation. For the general Nextstrain docs, go here: :doc:`docs.nextstrain.org:index` + These pages contain documentation automatically generated from docstrings within the augur codebase. They are intended for people developing augur or importing augur into their python scripts. If you are using `augur` as a command line program, then please see the `using augur <../usage/usage.html>`__ section. diff --git a/docs/conf.py b/docs/conf.py index 9649daff5..9c1b5f631 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -53,7 +53,7 @@ def prose_list(items): # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['recommonmark', 'sphinx.ext.autodoc', 'sphinxarg.ext', 'sphinx.ext.napoleon', 'sphinx_markdown_tables'] +extensions = ['recommonmark', 'sphinx.ext.autodoc', 'sphinxarg.ext', 'sphinx.ext.napoleon', 'sphinx_markdown_tables', 'sphinx.ext.intersphinx'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -88,3 +88,9 @@ def prose_list(items): html_css_files = [ 'css/custom.css', ] + +# -- Cross-project references ------------------------------------------------ + +intersphinx_mapping = { + 'docs.nextstrain.org': ('https://docs.nextstrain.org/en/migrate/', None), +} From d5d6743071c50206f1be179641883849769cf8a8 Mon Sep 17 00:00:00 2001 From: eharkins Date: Thu, 1 Oct 2020 13:25:23 -0400 Subject: [PATCH 02/16] only display reference guides --- docs/faq/faq.rst | 11 ++------- docs/faq/introduction-to-augur.md | 27 ++++++++++++++++++++ docs/faq/what-is-a-build.md | 41 +++++++++++++++++++++++++++++++ docs/index.rst | 1 - docs/usage/usage.rst | 1 - 5 files changed, 70 insertions(+), 11 deletions(-) create mode 100644 docs/faq/introduction-to-augur.md create mode 100644 docs/faq/what-is-a-build.md diff --git a/docs/faq/faq.rst b/docs/faq/faq.rst index bcb6e83d0..1f32c78d1 100644 --- a/docs/faq/faq.rst +++ b/docs/faq/faq.rst @@ -10,15 +10,8 @@ common questions and problems users run into. :maxdepth: 1 :glob: + introduction-to-augur + what-is-a-build metadata - translate_ref clades - community_hosting - import-beast - colors - lat_longs Specifying `refine` rates - Using Augur and Snakemake - vcf_input - fasta_input - seq_traits \ No newline at end of file diff --git a/docs/faq/introduction-to-augur.md b/docs/faq/introduction-to-augur.md new file mode 100644 index 000000000..4f61d0625 --- /dev/null +++ b/docs/faq/introduction-to-augur.md @@ -0,0 +1,27 @@ +# Augur: Nextstrain's Bioinformatics Toolkit + +Nextstrain's bioinformatics toolkit is called __Augur__. +It is a core part of the Nextstrain ecosystem used by all of our [pathogen builds](../../tutorials/index), and all source code is available on [GitHub](https://github.com/nextstrain/augur). + +Augur provides ways to perform common bioinformatics tasks through a collection of commands which are designed to be composable into larger processing pipelines. +This means the commands work well both independently and together, embracing the [philosophy of composability](https://en.wikipedia.org/wiki/Composability). + + +We've used Augur to analyze a bunch of different pathogens -- from viruses with tiny genomes like [Zika](../../tutorials/zika), to bacterial genomes orders-of-magnitude bigger like [tuberculosis](https://docs.nextstrain.org/projects/augur/en/stable/tutorials/tb_tutorial.html). +Check out the tutorials (via the sidebar to the left) to see which components we used in each one. + +Since we built it to be composable, it's easy to use other code or software to replace steps (or multiple steps!). +Similarly, not all available commands are applicable -- nor scientifically valid -- for different pathogen analyses. +We've used BEAST to replace multiple augur commands, but still visualize the results in auspice. +It's also common to have additional scripts which are called in-between different components; reading the different tutorials should give you a feel for how powerful these can be, and how versatile your builds can be! + + +### Explore in more depth: + +* Learn more about [each Augur command](https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/cli.html). + +* Learn more about the [data formats Augur uses and produces](../../reference/formats/data-formats). + +* See [how Augur commands are used in our Zika build](../../tutorials/zika). + + diff --git a/docs/faq/what-is-a-build.md b/docs/faq/what-is-a-build.md new file mode 100644 index 000000000..3ce36ff6a --- /dev/null +++ b/docs/faq/what-is-a-build.md @@ -0,0 +1,41 @@ +# The concept of a 'build' + +Nextstrain's focus on providing a _real-time_ snapshot of evolving pathogen populations necessitates a reproducible analysis that can be rerun when new sequences are available. +The individual steps necessary to repeat analysis together comprise a "build". + + +Because no two datasets or pathogens are the same, we build Augur to be flexible and suitable for different analyses. +The individual Augur commands are composable, and can be mixed and matched with other scripts as needed. +These steps, taken together, are what we refer to as a "build". + + +### Example build + +The [Zika virus tutorial](/docs/tutorials/zika#build-steps) describes a build which contains the following steps: + +1. Prepare pathogen sequences and metadata +2. Align sequences +3. Construct a phylogeny from aligned sequences +4. Annotate the phylogeny with inferred ancestral pathogen dates, sequences, and traits +5. Export the annotated phylogeny and corresponding metadata into auspice-readable format + +and each of these can be run via a separate `augur` command. + + + + +### Snakemake + +While it is possible to run a build by running each of the individual steps, we typically group these together into a make-type file. +[Snakemake](https://snakemake.readthedocs.io/en/stable/index.html) is "a tool to create reproducible and scalable data analyses... via a human-readable, Python-based language." + +> Snakemake is installed as part of the [conda environment](/docs/getting-started/local-installation#install-augur--auspice-with-conda-recommended) or the [docker container](/docs/getting-started/container-installation#install-docker). +If you ever see a build which has a "Snakefile" then you can run this by typing `snakemake --cores 1` or `nextstrain build --cpus 1 .`, respectively. + + +### Next steps + +* Have a look at some of the tutorials (listed in the sidebar). +Each one will use a slightly different combination of `augur` commands depending on the pathogen. + +* Visit the [augur docs](https://nextstrain-augur.readthedocs.io/en/stable) for more information on the bioinformatics toolkit. diff --git a/docs/index.rst b/docs/index.rst index d1e5669f8..ab76058d9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,7 +37,6 @@ The nextstrain team uses `snakemake `__ shows h :maxdepth: 2 cli/cli - augur_snakemake json_format envvars From 5fed06e622d7ccfaecfb35abce8eee2060e294fa Mon Sep 17 00:00:00 2001 From: eharkins Date: Thu, 1 Oct 2020 13:33:41 -0400 Subject: [PATCH 03/16] move warning / link to parent proj to index page --- docs/api/api.rst | 3 --- docs/index.rst | 3 +++ 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/api.rst b/docs/api/api.rst index a93d2cde7..c89729232 100644 --- a/docs/api/api.rst +++ b/docs/api/api.rst @@ -2,9 +2,6 @@ Python Development API ====================== -.. warning:: - This is the augur API reference documentation. For the general Nextstrain docs, go here: :doc:`docs.nextstrain.org:index` - These pages contain documentation automatically generated from docstrings within the augur codebase. They are intended for people developing augur or importing augur into their python scripts. If you are using `augur` as a command line program, then please see the `using augur <../usage/usage.html>`__ section. diff --git a/docs/index.rst b/docs/index.rst index ab76058d9..3aca1c560 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,6 +2,9 @@ Augur: A bioinformatics toolkit for phylogenetic analysis ========================================================= +.. warning:: + This is the augur project's reference documentation. For the general Nextstrain docs, go here: :doc:`docs.nextstrain.org:index` + *One held to foretell events by omens.* (`Merriam-Webster `__) From e1889479b602d4bf8c57ea8b9985625e3d499cd1 Mon Sep 17 00:00:00 2001 From: eharkins Date: Thu, 1 Oct 2020 13:43:18 -0400 Subject: [PATCH 04/16] fix warning mistake --- docs/index.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 3aca1c560..ce3baff07 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,11 +2,12 @@ Augur: A bioinformatics toolkit for phylogenetic analysis ========================================================= + *One held to foretell events by omens.* + (`Merriam-Webster `__) + .. warning:: This is the augur project's reference documentation. For the general Nextstrain docs, go here: :doc:`docs.nextstrain.org:index` - *One held to foretell events by omens.* - (`Merriam-Webster `__) Augur is a bioinformatics toolkit to track evolution from sequence and serological data. It provides a collection of commands which are designed to be composable into larger processing pipelines. From 0c4bf20dc29fe7ba82f575cc2fc25661e027354e Mon Sep 17 00:00:00 2001 From: eharkins Date: Mon, 19 Oct 2020 16:53:43 -0700 Subject: [PATCH 05/16] move DEV_DOCS to actual docs; this will be source at guides/contribute/augur using the submodule for this repo in docs.nextstrain.org --- README.md | 2 +- DEV_DOCS.md => docs/contribute/DEV_DOCS.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) rename DEV_DOCS.md => docs/contribute/DEV_DOCS.md (99%) diff --git a/README.md b/README.md index db07ecc3e..066754875 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ The output of augur is a series of JSONs that can be used to visualize your resu * [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) +* [Developer docs for Augur](./docs/contribute/DEV_DOCS.md) ## Quickstart diff --git a/DEV_DOCS.md b/docs/contribute/DEV_DOCS.md similarity index 99% rename from DEV_DOCS.md rename to docs/contribute/DEV_DOCS.md index cf483790e..77f83edf5 100644 --- a/DEV_DOCS.md +++ b/docs/contribute/DEV_DOCS.md @@ -1,6 +1,6 @@ -# Development Docs for Contributors +# Augur Development Docs for Contributors -Thank you for helping us to improve Nextstrain! This document describes: +Thank you for helping us to improve Augur! This document describes: - Getting Started - Contributing code From 83ee9c5bb13aa49c91f219e41af944220dac8d81 Mon Sep 17 00:00:00 2001 From: eharkins Date: Fri, 23 Oct 2020 15:42:59 -0700 Subject: [PATCH 06/16] docs link back to docs.nextstrain.org/en/latest; prepare for merging migrate into master in docs.nextstrain.org --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 9c1b5f631..16f66296f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -92,5 +92,5 @@ def prose_list(items): # -- Cross-project references ------------------------------------------------ intersphinx_mapping = { - 'docs.nextstrain.org': ('https://docs.nextstrain.org/en/migrate/', None), + 'docs.nextstrain.org': ('https://docs.nextstrain.org/en/latest/', None), } From 281a1798058c3fc0bc6dc8f7c760043dc1e26dbc Mon Sep 17 00:00:00 2001 From: james hadfield Date: Tue, 3 Nov 2020 17:51:56 +1300 Subject: [PATCH 07/16] [docs] Set theme (sidebar) options Part of an effort to standardize the appearance of the sidebar in subprojects. Settings chosen based on docs.nextstrain.org. --- docs/conf.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 16f66296f..0483b47a8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -78,6 +78,12 @@ def prose_list(items): # html_theme = 'nextstrain-sphinx-theme' +html_theme_options = { + 'logo_only': False, # if True, don't display project name at top of the sidebar + 'collapse_navigation': False, # if True, no [+] icons in sidebar + 'titles_only': True, # if True, page subheadings not included in nav +} + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". From c318a937293a35dfdb00718dea4ee06085055965 Mon Sep 17 00:00:00 2001 From: eharkins Date: Wed, 4 Nov 2020 11:27:55 -0800 Subject: [PATCH 08/16] remove intro page from faq section of docs --- docs/faq/faq.rst | 1 - docs/faq/introduction-to-augur.md | 27 --------------------------- 2 files changed, 28 deletions(-) delete mode 100644 docs/faq/introduction-to-augur.md diff --git a/docs/faq/faq.rst b/docs/faq/faq.rst index 1f32c78d1..9dfd5bb5b 100644 --- a/docs/faq/faq.rst +++ b/docs/faq/faq.rst @@ -10,7 +10,6 @@ common questions and problems users run into. :maxdepth: 1 :glob: - introduction-to-augur what-is-a-build metadata clades diff --git a/docs/faq/introduction-to-augur.md b/docs/faq/introduction-to-augur.md deleted file mode 100644 index 4f61d0625..000000000 --- a/docs/faq/introduction-to-augur.md +++ /dev/null @@ -1,27 +0,0 @@ -# Augur: Nextstrain's Bioinformatics Toolkit - -Nextstrain's bioinformatics toolkit is called __Augur__. -It is a core part of the Nextstrain ecosystem used by all of our [pathogen builds](../../tutorials/index), and all source code is available on [GitHub](https://github.com/nextstrain/augur). - -Augur provides ways to perform common bioinformatics tasks through a collection of commands which are designed to be composable into larger processing pipelines. -This means the commands work well both independently and together, embracing the [philosophy of composability](https://en.wikipedia.org/wiki/Composability). - - -We've used Augur to analyze a bunch of different pathogens -- from viruses with tiny genomes like [Zika](../../tutorials/zika), to bacterial genomes orders-of-magnitude bigger like [tuberculosis](https://docs.nextstrain.org/projects/augur/en/stable/tutorials/tb_tutorial.html). -Check out the tutorials (via the sidebar to the left) to see which components we used in each one. - -Since we built it to be composable, it's easy to use other code or software to replace steps (or multiple steps!). -Similarly, not all available commands are applicable -- nor scientifically valid -- for different pathogen analyses. -We've used BEAST to replace multiple augur commands, but still visualize the results in auspice. -It's also common to have additional scripts which are called in-between different components; reading the different tutorials should give you a feel for how powerful these can be, and how versatile your builds can be! - - -### Explore in more depth: - -* Learn more about [each Augur command](https://docs.nextstrain.org/projects/augur/en/stable/usage/cli/cli.html). - -* Learn more about the [data formats Augur uses and produces](../../reference/formats/data-formats). - -* See [how Augur commands are used in our Zika build](../../tutorials/zika). - - From db422a7d5d16459b6a3fe9c696341605934721d6 Mon Sep 17 00:00:00 2001 From: eharkins Date: Wed, 4 Nov 2020 11:28:50 -0800 Subject: [PATCH 09/16] docs index page: add links to non-reference docs --- docs/index.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index ce3baff07..0e1547a71 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,13 +5,19 @@ Augur: A bioinformatics toolkit for phylogenetic analysis *One held to foretell events by omens.* (`Merriam-Webster `__) -.. warning:: - This is the augur project's reference documentation. For the general Nextstrain docs, go here: :doc:`docs.nextstrain.org:index` +.. note:: + The documentation you are viewing is Augur's reference guide, which means it is information-oriented and targeted at users who just need info about how Augur works. + + * If you have a question about how to achieve a specific goal with Augur, check out our :doc:`Augur-focused How-to Guides section ` in the main Nextstrain documentation. + * If you want to learn the basics of how to use Augur from scratch, check out our :doc:`Zika tutorial ` in the main Nextstrain documentation. + * If you want to understand how Augur fits together with Auspice to visualize results, check out our :doc:`Data Formats section ` in the main Nextstrain documentation. + Augur is a bioinformatics toolkit to track evolution from sequence and serological data. It provides a collection of commands which are designed to be composable into larger processing pipelines. Augur originated as part of `Nextstrain `__, an open-source project to harness the scientific and public health potential of pathogen genome data. +All source code is available on [GitHub](https://github.com/nextstrain/augur). .. note:: We have just released version 6 of augur -- `check our upgrading guide `__ @@ -30,7 +36,6 @@ The ``refine`` step is necessary to ensure that cross-referencing between tree n The different augur modules can be strung together by workflow managers like snakemake and nextflow. The nextstrain team uses `snakemake `__ to run and manage the different analysis that you see on `nextstrain.org `__. - .. toctree:: :maxdepth: 2 :caption: Table of contents From 0bbd195d678c9de9397b9f7678761a9cc8b14485 Mon Sep 17 00:00:00 2001 From: eharkins Date: Wed, 4 Nov 2020 11:31:47 -0800 Subject: [PATCH 10/16] fix what-is-a-build page; this page came from nextstrain.org/docs and so had broken links and language that didn't make sense in the augur docs. This fixes those issues to make it more useful in this new context --- docs/faq/what-is-a-build.md | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/docs/faq/what-is-a-build.md b/docs/faq/what-is-a-build.md index 3ce36ff6a..37191b472 100644 --- a/docs/faq/what-is-a-build.md +++ b/docs/faq/what-is-a-build.md @@ -11,7 +11,7 @@ These steps, taken together, are what we refer to as a "build". ### Example build -The [Zika virus tutorial](/docs/tutorials/zika#build-steps) describes a build which contains the following steps: +The [Zika virus tutorial](https://docs.nextstrain.org/en/latest/tutorials/zika.html#build-steps) describes a build which contains the following steps: 1. Prepare pathogen sequences and metadata 2. Align sequences @@ -21,21 +21,12 @@ The [Zika virus tutorial](/docs/tutorials/zika#build-steps) describes a build wh and each of these can be run via a separate `augur` command. - - +If you look at the [other tutorials](https://docs.nextstrain.org/en/latest/tutorials/index.html), each one uses a slightly different combination of `augur` commands depending on the pathogen. ### Snakemake While it is possible to run a build by running each of the individual steps, we typically group these together into a make-type file. [Snakemake](https://snakemake.readthedocs.io/en/stable/index.html) is "a tool to create reproducible and scalable data analyses... via a human-readable, Python-based language." -> Snakemake is installed as part of the [conda environment](/docs/getting-started/local-installation#install-augur--auspice-with-conda-recommended) or the [docker container](/docs/getting-started/container-installation#install-docker). +> Snakemake is installed as part of the [conda environment](https://docs.nextstrain.org/en/latest/guides/install/local-installation.html#install-augur-auspice-with-conda) or the [docker container](https://docs.nextstrain.org/en/latest/cli/doc/installation.html). If you ever see a build which has a "Snakefile" then you can run this by typing `snakemake --cores 1` or `nextstrain build --cpus 1 .`, respectively. - - -### Next steps - -* Have a look at some of the tutorials (listed in the sidebar). -Each one will use a slightly different combination of `augur` commands depending on the pathogen. - -* Visit the [augur docs](https://nextstrain-augur.readthedocs.io/en/stable) for more information on the bioinformatics toolkit. From 02978922ac83d32c39a06f06203bc56326b310e0 Mon Sep 17 00:00:00 2001 From: eharkins Date: Wed, 4 Nov 2020 11:39:31 -0800 Subject: [PATCH 11/16] fix docs index.rst github link --- docs/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 0e1547a71..3e4774765 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,7 @@ Augur: A bioinformatics toolkit for phylogenetic analysis (`Merriam-Webster `__) .. note:: - The documentation you are viewing is Augur's reference guide, which means it is information-oriented and targeted at users who just need info about how Augur works. + The documentation you are viewing is Augur's reference guide, which means it is information-oriented and targeted at users who just need info about how Augur works. * If you have a question about how to achieve a specific goal with Augur, check out our :doc:`Augur-focused How-to Guides section ` in the main Nextstrain documentation. * If you want to learn the basics of how to use Augur from scratch, check out our :doc:`Zika tutorial ` in the main Nextstrain documentation. @@ -17,7 +17,7 @@ Augur: A bioinformatics toolkit for phylogenetic analysis Augur is a bioinformatics toolkit to track evolution from sequence and serological data. It provides a collection of commands which are designed to be composable into larger processing pipelines. Augur originated as part of `Nextstrain `__, an open-source project to harness the scientific and public health potential of pathogen genome data. -All source code is available on [GitHub](https://github.com/nextstrain/augur). +All source code is available on `GitHub `__. .. note:: We have just released version 6 of augur -- `check our upgrading guide `__ From 13e88b78169a1eb20385f669fea85ea752388d74 Mon Sep 17 00:00:00 2001 From: eharkins Date: Wed, 4 Nov 2020 12:17:51 -0800 Subject: [PATCH 12/16] docs: fix 404s resulting from migration; some documents are no longer in this repo or no longer linked in a toctree so this updates links to send you to their new location in docs.nextstrain.org --- docs/releases/migrating-v5-v6.md | 4 ++-- docs/releases/v6.md | 4 ++-- docs/usage/cli/filter.rst | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/releases/migrating-v5-v6.md b/docs/releases/migrating-v5-v6.md index df3360bbd..6d9eef8e2 100644 --- a/docs/releases/migrating-v5-v6.md +++ b/docs/releases/migrating-v5-v6.md @@ -119,7 +119,7 @@ These may have been inferred for internal nodes by Augur functions like `augur t Certain traits have a geographic interpretation, e.g. "country". Auspice will attempt to display these traits on a map (and provide a drop-down to switch between them if there are more than one). -> _Make sure that these have corresponding entry in the lat-longs TSV file supplied to `export`. See how to do this [here](/faq/lat_longs)._ +> _Make sure that these have corresponding entry in the lat-longs TSV file supplied to `export`. See how to do this [here](https://docs.nextstrain.org/en/latest/augur/docs/faq/lat_longs.html)._ --- @@ -528,5 +528,5 @@ In Auspice v2, all values are now displayed exactly as they arrive, allowing use Don't forget to also change them in any custom lat-long and/or coloring files you are using. We've also become stricter about the format of the files that pass in color and lat-long information. Previously, it didn't matter if columns were separated by spaces or tabs - now, they must be separated by tabs. -You can find out more about how to add [custom coloring](/faq/colors) and [lat-long](/faq/lat_longs) values. +You can find out more about how to add [custom coloring](https://docs.nextstrain.org/en/latest/augur/docs/faq/colors.html) and [lat-long](https://docs.nextstrain.org/en/latest/augur/docs/faq/lat_longs.html) values. If you use the command `parse` to generate a metadata table from fields in a fasta header, you can use the flag `--prettify-fields` to apply some prettifying operations to specific metadata entries, see the documentation [`parse`](/usage/cli/parse). diff --git a/docs/releases/v6.md b/docs/releases/v6.md index 0d75a53a6..359b2a250 100644 --- a/docs/releases/v6.md +++ b/docs/releases/v6.md @@ -46,7 +46,7 @@ Users can ask for this output and specify a file name using `--output-sequences` Deprecation warning: The argument `--output` is now deprecated. Please use `--output-node-data` instead. ## Import BEAST MCC trees -We now have instructions and functionality to import BEAST trees, see [here](/faq/import-beast). +We now have instructions and functionality to import BEAST trees, see [here](https://docs.nextstrain.org/en/latest/augur/docs/faq/import-beast.html). ## Prettifying of strings Previous auspice version "prettified" metadata strings (like changing 'north_america' to 'North America'). @@ -110,4 +110,4 @@ We've tried to use redirects to ensure that all the old links continue to work. * Errors in formatting of input files (e.g. metadata files, Auspice config files) weren't handled nicely, often resulting in hard-to-interpret stack traces. We now try to catch these and print an error indicating the offending file. -* Tests using Python version 2 have now been removed. \ No newline at end of file +* Tests using Python version 2 have now been removed. diff --git a/docs/usage/cli/filter.rst b/docs/usage/cli/filter.rst index f34c0bdbe..5c6a31542 100644 --- a/docs/usage/cli/filter.rst +++ b/docs/usage/cli/filter.rst @@ -15,7 +15,7 @@ augur filter How we subsample sequences in the zika-tutoral ============================================== -As an example, we'll look that the ``filter`` command in greater detail using material form the `zika tutorial <../../tutorials/zika_tutorial.html>`__. +As an example, we'll look that the ``filter`` command in greater detail using material form the :doc:`zika tutorial `. The filter command allows you to selected various subsets of your input data for different types of analysis. A simple example use of this command would be @@ -45,7 +45,7 @@ To drop such strains, you can pass the name of this file to the augur filter com --output filtered.fasta (To improve legibility, we have wrapped the command across multiple lines.) -If you run this command (you should be able to copy-paste this into your terminal) on the data provided in the `zika tutorial `__, you should see that one of the sequences in the data set was dropped since its name was in the ``dropped_strains.txt`` file. +If you run this command (you should be able to copy-paste this into your terminal) on the data provided in the :doc:`zika tutorial `, you should see that one of the sequences in the data set was dropped since its name was in the ``dropped_strains.txt`` file. Another common filtering operation is subsetting of data to a achieve a more even spatio-temporal distribution or to cut-down data set size to more manageable numbers. The filter command allows you to select a specific number of sequences from specific groups, for example one sequence per month from each country: From e6aad6164dcd3d82291cb0c3979e2569d331df64 Mon Sep 17 00:00:00 2001 From: eharkins Date: Wed, 4 Nov 2020 17:29:01 -0800 Subject: [PATCH 13/16] remove unused docs --- docs/faq/augur_snakemake.md | 1 - docs/faq/community_hosting.md | 45 ----------------------------------- docs/tutorials/tutorials.rst | 12 ---------- 3 files changed, 58 deletions(-) delete mode 120000 docs/faq/augur_snakemake.md delete mode 100644 docs/faq/community_hosting.md delete mode 100644 docs/tutorials/tutorials.rst diff --git a/docs/faq/augur_snakemake.md b/docs/faq/augur_snakemake.md deleted file mode 120000 index c45f33e95..000000000 --- a/docs/faq/augur_snakemake.md +++ /dev/null @@ -1 +0,0 @@ -../usage/augur_snakemake.md \ No newline at end of file diff --git a/docs/faq/community_hosting.md b/docs/faq/community_hosting.md deleted file mode 100644 index 79de1689b..000000000 --- a/docs/faq/community_hosting.md +++ /dev/null @@ -1,45 +0,0 @@ -# Sharing your analysis - -[nextstrain.org](https://nextstrain.org) has a feature that allows you to share your own analysis through the nextstrain.org website. -This works using github as a repository for your analysis files. -To share an analysis, you need to create a repository. -The name of the repository will be what is used to access the results. -Within this repository, there should a folder called auspice which contains the output json files of the augur pipeline. -Importantly, the name of these files has to start with the name of the repository. -If so, you should be able to access your analysis via the nextstrain community feature. - -As an example, lets look at one of our nextstrain community analysis. -The following link shows you an analysis we made a few month ago of many influenza B sequences: - -[nextstrain.org/community/neherlab/allflu/B_ha](https://nextstrain.org/community/neherlab/allflu/B_ha) - -The analysis files are hosted on our github page in the reposity - -[github.com/neherlab/allflu](https://github.com/neherlab/allflu) - -In this repository, you'll find the folder `auspice` which contains the files -``` -allflu_B_ha_meta.json -allflu_B_ha_tree.json -``` -Note that all files start with "allflu" which matches the name of the repository. -In fact, there are multiple analysis in this folder. The corresponding files all start with "allflu" but they differ in the viral lineage they correspond to: -``` -allflu_B_ha_meta.json -allflu_B_ha_tree.json -allflu_h1n1_ha_meta.json -allflu_h1n1_ha_tree.json -allflu_h1n1pdm_ha_meta.json -allflu_h1n1pdm_ha_tree.json -allflu_h3n2_ha_meta.json -allflu_h3n2_ha_tree.json -``` -All these can be accessed as - -[nextstrain.org/community/neherlab/allflu/h1n1_ha](https://nextstrain.org/community/neherlab/allflu/h1n1_ha) - -[nextstrain.org/community/neherlab/allflu/h3n2_ha](https://nextstrain.org/community/neherlab/allflu/h3n2_ha) - -[nextstrain.org/community/neherlab/allflu/h1n1pdm_ha](https://nextstrain.org/community/neherlab/allflu/h1n1pdm_ha) - - diff --git a/docs/tutorials/tutorials.rst b/docs/tutorials/tutorials.rst deleted file mode 100644 index 831ee9a90..000000000 --- a/docs/tutorials/tutorials.rst +++ /dev/null @@ -1,12 +0,0 @@ -========= -Tutorials -========= - -.. note:: We have just released version 6 of augur -- `check our upgrading guide <../releases/migrating-v5-v6.html>`__ - -.. toctree:: - :maxdepth: 1 - :caption: Available tutorials - - zika_tutorial - tb_tutorial From 4ab45e7bdf202dcf92ee5fe712d3b2b6222ccdd8 Mon Sep 17 00:00:00 2001 From: eharkins Date: Wed, 4 Nov 2020 20:15:29 -0800 Subject: [PATCH 14/16] exclude unused docs from build --- docs/conf.py | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 0483b47a8..d1d2ffea3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -61,7 +61,19 @@ def prose_list(items): # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', + 'contribute/DEV_DOCS.md', + 'faq/colors.md', + 'faq/fasta_input.md', + 'faq/import-beast.md', + 'faq/lat_longs.md', + 'faq/seq_traits.md', + 'faq/translate_ref.md', + 'faq/vcf_input.md', + 'tutorials/tb_tutorial.md', + 'tutorials/zika_tutorial.md', + 'usage/augur_snakemake.md', +] # A string of reStructuredText that will be included at the end of every source # file that is read. This is a possible place to add substitutions that should From 02a1906d1a757d87d30eb3f5aacc9f0caa78d282 Mon Sep 17 00:00:00 2001 From: eharkins Date: Sat, 7 Nov 2020 14:37:34 -0800 Subject: [PATCH 15/16] [fetch-docs] relative links this relative link did not work after fetching this doc into docs.nextstrain.org because the folder structure is different from this repo so this changes it to fit with that of docs.nextstrain.org. this means the relative link breaks in this repo but this document is not rendered in this repo's docs. This will need to remain this way or become an absolute link until we have a unified toctree. --- docs/tutorials/tb_tutorial.md | 2 +- docs/tutorials/zika_tutorial.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/tb_tutorial.md b/docs/tutorials/tb_tutorial.md index 8b9b095fe..c40b2965e 100644 --- a/docs/tutorials/tb_tutorial.md +++ b/docs/tutorials/tb_tutorial.md @@ -7,7 +7,7 @@ As in the Zika fasta-input [tutorial](zika_tutorial), we'll build up a Snakefile ## Setup -To run this tutorial you'll need to [install augur](../installation/installation) and [install Snakemake](https://snakemake.readthedocs.io/en/stable/getting_started/installation.html). +To run this tutorial you'll need to [install augur](../guides/install/augur_install.md) and [install Snakemake](https://snakemake.readthedocs.io/en/stable/getting_started/installation.html). ## Build steps Nextstrain builds typically require the following steps: diff --git a/docs/tutorials/zika_tutorial.md b/docs/tutorials/zika_tutorial.md index 69ffbdc96..f7bafb66b 100644 --- a/docs/tutorials/zika_tutorial.md +++ b/docs/tutorials/zika_tutorial.md @@ -7,7 +7,7 @@ We will work off the tutorial for Zika virus on the [nextstrain web site](https: ## Setup -To run this tutorial you'll need to [install augur](../installation/installation) and [install Snakemake](https://snakemake.readthedocs.io/en/stable/getting_started/installation.html). +To run this tutorial you'll need to [install augur](../guides/install/augur_install.md) and [install Snakemake](https://snakemake.readthedocs.io/en/stable/getting_started/installation.html). ## Augur commands From fa384d1b4f1b8f91f8cc6409110cf45b89d30c86 Mon Sep 17 00:00:00 2001 From: Elias Harkins Date: Wed, 11 Nov 2020 15:53:44 -0800 Subject: [PATCH 16/16] [fetch-docs] update links Update links according to URLs resulting from the merging of https://github.com/nextstrain/docs.nextstrain.org/pull/36 --- docs/faq/what-is-a-build.md | 2 +- docs/index.rst | 2 +- docs/releases/migrating-v5-v6.md | 6 ++++-- docs/releases/v6.md | 2 +- docs/usage/cli/filter.rst | 4 ++-- 5 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/faq/what-is-a-build.md b/docs/faq/what-is-a-build.md index 37191b472..405c67163 100644 --- a/docs/faq/what-is-a-build.md +++ b/docs/faq/what-is-a-build.md @@ -28,5 +28,5 @@ If you look at the [other tutorials](https://docs.nextstrain.org/en/latest/tutor While it is possible to run a build by running each of the individual steps, we typically group these together into a make-type file. [Snakemake](https://snakemake.readthedocs.io/en/stable/index.html) is "a tool to create reproducible and scalable data analyses... via a human-readable, Python-based language." -> Snakemake is installed as part of the [conda environment](https://docs.nextstrain.org/en/latest/guides/install/local-installation.html#install-augur-auspice-with-conda) or the [docker container](https://docs.nextstrain.org/en/latest/cli/doc/installation.html). +> Snakemake is installed as part of the [conda environment](https://docs.nextstrain.org/en/latest/guides/install/local-installation.html#install-augur-auspice-with-conda) or the [docker container](https://docs.nextstrain.org/en/latest/guides/install/cli-install.html). If you ever see a build which has a "Snakefile" then you can run this by typing `snakemake --cores 1` or `nextstrain build --cpus 1 .`, respectively. diff --git a/docs/index.rst b/docs/index.rst index 3e4774765..ead0a788c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,7 +9,7 @@ Augur: A bioinformatics toolkit for phylogenetic analysis The documentation you are viewing is Augur's reference guide, which means it is information-oriented and targeted at users who just need info about how Augur works. * If you have a question about how to achieve a specific goal with Augur, check out our :doc:`Augur-focused How-to Guides section ` in the main Nextstrain documentation. - * If you want to learn the basics of how to use Augur from scratch, check out our :doc:`Zika tutorial ` in the main Nextstrain documentation. + * If you want to learn the basics of how to use Augur from scratch, check out our :doc:`Zika tutorial ` in the main Nextstrain documentation. * If you want to understand how Augur fits together with Auspice to visualize results, check out our :doc:`Data Formats section ` in the main Nextstrain documentation. diff --git a/docs/releases/migrating-v5-v6.md b/docs/releases/migrating-v5-v6.md index 6d9eef8e2..23512f81c 100644 --- a/docs/releases/migrating-v5-v6.md +++ b/docs/releases/migrating-v5-v6.md @@ -119,7 +119,8 @@ These may have been inferred for internal nodes by Augur functions like `augur t Certain traits have a geographic interpretation, e.g. "country". Auspice will attempt to display these traits on a map (and provide a drop-down to switch between them if there are more than one). -> _Make sure that these have corresponding entry in the lat-longs TSV file supplied to `export`. See how to do this [here](https://docs.nextstrain.org/en/latest/augur/docs/faq/lat_longs.html)._ +> _Make sure that these have corresponding entry in the lat-longs TSV file supplied to `export`. See how to do this [here](https://docs.nextstrain.org/en/latest/guides/bioinformatics/lat_longs.html)._ + --- @@ -528,5 +529,6 @@ In Auspice v2, all values are now displayed exactly as they arrive, allowing use Don't forget to also change them in any custom lat-long and/or coloring files you are using. We've also become stricter about the format of the files that pass in color and lat-long information. Previously, it didn't matter if columns were separated by spaces or tabs - now, they must be separated by tabs. -You can find out more about how to add [custom coloring](https://docs.nextstrain.org/en/latest/augur/docs/faq/colors.html) and [lat-long](https://docs.nextstrain.org/en/latest/augur/docs/faq/lat_longs.html) values. +You can find out more about how to add [custom coloring](https://docs.nextstrain.org/en/latest/guides/bioinformatics/colors.html) and [lat-long](https://docs.nextstrain.org/en/latest/guides/bioinformatics/lat_longs.html) values. + If you use the command `parse` to generate a metadata table from fields in a fasta header, you can use the flag `--prettify-fields` to apply some prettifying operations to specific metadata entries, see the documentation [`parse`](/usage/cli/parse). diff --git a/docs/releases/v6.md b/docs/releases/v6.md index 359b2a250..9bdbcec9d 100644 --- a/docs/releases/v6.md +++ b/docs/releases/v6.md @@ -46,7 +46,7 @@ Users can ask for this output and specify a file name using `--output-sequences` Deprecation warning: The argument `--output` is now deprecated. Please use `--output-node-data` instead. ## Import BEAST MCC trees -We now have instructions and functionality to import BEAST trees, see [here](https://docs.nextstrain.org/en/latest/augur/docs/faq/import-beast.html). +We now have instructions and functionality to import BEAST trees, see [here](https://docs.nextstrain.org/en/latest/guides/bioinformatics/import-beast.html). ## Prettifying of strings Previous auspice version "prettified" metadata strings (like changing 'north_america' to 'North America'). diff --git a/docs/usage/cli/filter.rst b/docs/usage/cli/filter.rst index 5c6a31542..3ebf97072 100644 --- a/docs/usage/cli/filter.rst +++ b/docs/usage/cli/filter.rst @@ -15,7 +15,7 @@ augur filter How we subsample sequences in the zika-tutoral ============================================== -As an example, we'll look that the ``filter`` command in greater detail using material form the :doc:`zika tutorial `. +As an example, we'll look that the ``filter`` command in greater detail using material form the :doc:`zika tutorial `. The filter command allows you to selected various subsets of your input data for different types of analysis. A simple example use of this command would be @@ -45,7 +45,7 @@ To drop such strains, you can pass the name of this file to the augur filter com --output filtered.fasta (To improve legibility, we have wrapped the command across multiple lines.) -If you run this command (you should be able to copy-paste this into your terminal) on the data provided in the :doc:`zika tutorial `, you should see that one of the sequences in the data set was dropped since its name was in the ``dropped_strains.txt`` file. +If you run this command (you should be able to copy-paste this into your terminal) on the data provided in the :doc:`zika tutorial `, you should see that one of the sequences in the data set was dropped since its name was in the ``dropped_strains.txt`` file. Another common filtering operation is subsetting of data to a achieve a more even spatio-temporal distribution or to cut-down data set size to more manageable numbers. The filter command allows you to select a specific number of sequences from specific groups, for example one sequence per month from each country: