transition to new docs (#596)

gregcaporaso · web-flow · commit 91710b9ad5aa · 2025-04-24T13:36:13.000-07:00
integrate a warning on all pages that redirects users to https://amplicon-docs.qiime2.org.
diff --git a/source/_old_docs_warning.rst b/source/_old_docs_warning.rst
@@ -0,0 +1,14 @@
+.. warning::
+   This site has been replaced by the new QIIME 2 "amplicon distribution" documentation, as of the 2025.4 release of QIIME 2.
+   You can still access the content from the "old docs" here for the QIIME 2 2024.10 and earlier releases, but we recommend that you transition to the new documentation at https://amplicon-docs.qiime2.org.
+   **Content on this site is no longer updated and may be out of date.**
+
+   Are you looking for:
+
+   - the QIIME 2 homepage? That's https://qiime2.org.
+   - learning resources for microbiome marker gene (i.e., amplicon) analysis? See the `QIIME 2 amplicon distribution documentation <https://amplicon-docs.qiime2.org>`_.
+   - learning resources for microbiome metagenome analysis? See the `MOSHPIT documentation <https://moshpit.qiime2.org>`_.
+   - installation instructions, plugins, books, videos, workshops, or resources? See the `QIIME 2 Library <https://library.qiime2.org>`_.
+   - general help? See the `QIIME 2 Forum <https://forum.qiime2.org>`_.
+
+   **Old content beyond this point...** 👴👵
diff --git a/source/_templates/action.rst b/source/_templates/action.rst
@@ -1,3 +1,5 @@
+.. include:: ../../../_old_docs_warning.rst
+
 {{ title }}
 {{ '=' * title|length }}
 
diff --git a/source/_templates/available.rst b/source/_templates/available.rst
@@ -1,6 +1,8 @@
 Available plugins
 =================
 
+.. include:: ../../_old_docs_warning.rst
+
 QIIME 2 microbiome analysis functionality is made available to users via plugins. The following official plugins are currently included in QIIME 2 train releases:
 
 .. toctree::
diff --git a/source/_templates/plugin.rst b/source/_templates/plugin.rst
@@ -1,3 +1,5 @@
+.. include:: ../../../_old_docs_warning.rst
+
 {{ title }}
 {{ '=' * title|length }}
 
diff --git a/source/about.rst b/source/about.rst
@@ -1,6 +1,8 @@
 What is QIIME 2?
 ================
 
+.. include:: _old_docs_warning.rst
+
 QIIME 2 is a powerful, extensible, and decentralized microbiome analysis package with a focus on data and analysis transparency. QIIME 2 enables researchers to start an analysis with raw DNA sequence data and finish with publication-quality figures and statistical results.
 
 Key features:
diff --git a/source/citation.rst b/source/citation.rst
@@ -1,6 +1,8 @@
 Citing QIIME 2
 ==============
 
+.. include:: _old_docs_warning.rst
+
 Please note that almost all QIIME 2 plugins implement methods that were developed independently of the QIIME 2 framework, which should be cited in addition to the QIIME 2 framework itself. This information can be extracted as described below.
 
 If you use QIIME 2 in your research, please cite the following `paper`_:
@@ -35,7 +37,7 @@ Each time any action is performed in QIIME 2, that information is logged in the
 2. Click on the "Provenance" tab in the upper right-hand corner of the browser window.
 3. Click on the "Citations" tab that appears in the window below to view a list of citations.
 4. Click "Download" to download the list in BibTeX format.
-5. Review the citations list and use common sense to make sure that you are citing all software and methods appropriately. If you notice any discrepancies in the citations that are listed by any QIIME 2 plugin, please verify which plugin/action is missing citations or mis-citing, using the directions above for retrieving plugin-specific citation information. Then get in touch on the `QIIME 2 forum`_ to let us know!
+5. Review the citations list and use common sense to make sure that you are citing all software and methods appropriately. If you notice any discrepancies in the citations that are listed by any QIIME 2 plugin, please verify which plugin/action is missing citations or mis-citing, using the directions above for retrieving plugin-specific citation information. Then get in touch on the QIIME 2 Forum to let us know!
 
 
 Example methods descriptions
@@ -72,5 +74,4 @@ This methods section was adapted from `Pearson et al. 2019`_ (and shortened in t
 .. _paper: https://doi.org/10.1038/s41587-019-0209-9
 .. _VSEARCH: https://github.com/torognes/vsearch
 .. _q2-feature-classifier: https://doi.org/10.1186/s40168-018-0470-z
-.. _QIIME 2 forum: https://forum.qiime2.org/
 .. _Pearson et al. 2019: https://doi.org/10.1002/cam4.1965
diff --git a/source/community.rst b/source/community.rst
@@ -1,12 +1,14 @@
 Community
 =========
 
+.. include:: _old_docs_warning.rst
+
 There are several ways to get in touch with the QIIME 2 community and stay up-to-date with QIIME 2 activity.
 
 QIIME 2 Forum
 -------------
 
-Visit the `QIIME 2 forum`_ for QIIME 2 support and to talk with other users and developers about all things related to QIIME 2.
+Visit the QIIME 2 Forum for QIIME 2 support and to talk with other users and developers about all things related to QIIME 2.
 
 Staying updated
 ---------------
@@ -19,5 +21,3 @@ Requesting features, reporting bugs, providing feedback
 If there is specific functionality you'd like to see in QIIME 2, you notice a bug, or want to leave feedback, please post to the `QIIME 2 forum`_. We appreciate all feedback as we strive to make QIIME 2 a useful and accessible tool for microbiome analyses.
 
 .. _`@qiime2`: https://twitter.com/qiime2
-
-.. _`QIIME 2 forum`: https://forum.qiime2.org
diff --git a/source/concepts.rst b/source/concepts.rst
@@ -1,6 +1,8 @@
 Core concepts
 =============
 
+.. include:: _old_docs_warning.rst
+
 This page describes several core concepts in QIIME 2 that are important to understand before starting to use the software. The :doc:`glossary <glossary>` may be helpful to refer to as you read through this page and other documentation on the site.
 
 Data files: QIIME 2 artifacts
diff --git a/source/conf.py b/source/conf.py
@@ -92,7 +92,7 @@ def setup(app):
 
 # General information about the project.
 project = 'QIIME 2'
-copyright = '2016-2024, QIIME 2 development team'
+copyright = '2016-2025, QIIME 2 development team'
 author = 'QIIME 2 development team'
 
 # The version info for the project you're documenting, acts as replacement for
diff --git a/source/data-resources.rst b/source/data-resources.rst
@@ -1,6 +1,8 @@
 Data resources
 ==============
 
+.. include:: _old_docs_warning.rst
+
 Taxonomy classifiers for use with q2-feature-classifier
 -------------------------------------------------------
 
diff --git a/source/getting-started.rst b/source/getting-started.rst
@@ -1,6 +1,8 @@
 Getting started
 ===============
 
+.. include:: _old_docs_warning.rst
+
 This guide will walk you through the steps necessary to understand, install, and use QIIME 2 for your own microbiome analyses:
 
 1. Familiarize yourself with the :doc:`core concepts <concepts>` of QIIME 2 before starting to use the system.
diff --git a/source/glossary.rst b/source/glossary.rst
@@ -1,6 +1,8 @@
 User Glossary
 =============
 
+.. include:: _old_docs_warning.rst
+
 There are two glossaries for QIIME 2: one geared toward users (this document),
 and another geared toward developers. You can find the
 `Developer Glossary here <https://dev.qiime2.org/latest/glossary/>`_.
@@ -145,18 +147,18 @@ and another geared toward developers. You can find the
      See :term:`visualization`.
 
    rarefy
-     A technique to remove uneven sampling depth by subsampling without 
+     A technique to remove uneven sampling depth by subsampling without
      replacement so that all :term: `samples <sample>` have the same sampling
-     depth. See `Schloss (2024) <https://doi.org/10.1128/msphere.00355-23>` for additional information. 
-     
+     depth. See `Schloss (2024) <https://doi.org/10.1128/msphere.00355-23>` for additional information.
+
 
    rarefaction
-     An iterative technique to minimize effects of controlling for uneven 
-     sampling depth where a feature table is :term:`rarefied<rarefy>` 
-     multiple times (typically 100 or 1000), and diversity 
+     An iterative technique to minimize effects of controlling for uneven
+     sampling depth where a feature table is :term:`rarefied<rarefy>`
+     multiple times (typically 100 or 1000), and diversity
      metrics are applied to each rarefied table and subsequently used to
-     compute summary statistics. See `Schloss (2024) <https://doi.org/10.1128/msphere.00355-23>` for additional information. 
-     
+     compute summary statistics. See `Schloss (2024) <https://doi.org/10.1128/msphere.00355-23>` for additional information.
+
    result
      A general term for an :term:`artifact` or a :term:`visualization`.
 
diff --git a/source/index.rst b/source/index.rst
@@ -1,12 +1,7 @@
-QIIME 2 user documentation
-==========================
+This is the "old" QIIME 2 user documentation
+============================================
 
-This site is the official user documentation for QIIME™ 2, including installation instructions, tutorials, and other important information. Visit http://qiime.org for information on QIIME™ 1.
-
-Getting started
----------------
-
-Check out the :doc:`getting started <getting-started>` guide to begin using QIIME 2.
+.. include:: _old_docs_warning.rst
 
 Table of contents
 -----------------
@@ -28,5 +23,3 @@ Table of contents
    supplementary-resources
    glossary
    citation
-
-.. _QIIME 1: http://qiime.org
diff --git a/source/install/index.rst b/source/install/index.rst
@@ -1,6 +1,8 @@
 Installing QIIME 2
 ==================
 
+.. include:: ../_old_docs_warning.rst
+
 QIIME 2 can be installed natively or using a virtual machine. The following
 pages describe how to install the available :ref:`distributions`
 in either scenario.
diff --git a/source/install/native.rst b/source/install/native.rst
@@ -1,6 +1,8 @@
 Natively installing QIIME 2
 ===========================
 
+.. include:: ../_old_docs_warning.rst
+
 This guide describes how to natively install the available :ref:`distributions`.
 
 Miniconda
diff --git a/source/install/virtual/docker.rst b/source/install/virtual/docker.rst
@@ -1,6 +1,8 @@
 Installing QIIME 2 using Docker
 ===============================
 
+.. include:: ../../_old_docs_warning.rst
+
 The following QIIME 2 distributions are available as Docker images:
 
 - ``amplicon``
diff --git a/source/install/virtual/index.rst b/source/install/virtual/index.rst
@@ -1,6 +1,8 @@
 Installing QIIME 2 using a Virtual Machine
 ==========================================
 
+.. include:: ../../_old_docs_warning.rst
+
 *QIIME 2 Distribution* builds are available as Docker Images. See :ref:`distributions` for more details about the available distributions.
 
 .. toctree::
diff --git a/source/install/virtual/wsl.rst b/source/install/virtual/wsl.rst
@@ -1,6 +1,8 @@
 Installing QIIME 2 using WSL
 ----------------------------
 
+.. include:: ../../_old_docs_warning.rst
+
 Please see the `official Microsoft guide`_ to install and set up the WSL. Once
 you have installed and set up the WSL, install a Linux distribution (step 6 of
 the WSL guide). We suggest the latest stable version of `Ubuntu`_.
@@ -14,4 +16,3 @@ setting up and using the WSL.
 
 .. _official Microsoft guide: https://docs.microsoft.com/en-us/windows/wsl/install-win10
 .. _Ubuntu: https://wiki.ubuntu.com/WSL
-.. _QIIME 2 Forum: https://forum.qiime2.org/search?q=WSL%20%23community-contributions
diff --git a/source/interfaces/artifact-api.rst b/source/interfaces/artifact-api.rst
@@ -1,6 +1,8 @@
 Artifact API (using QIIME 2 with Python)
 ========================================
 
+.. include:: ../_old_docs_warning.rst
+
 .. note:: This guide assumes you have performed the steps in the :doc:`Moving Pictures tutorial <../tutorials/moving-pictures>`. The ``table.qza`` and ``sample-metadata.tsv`` files generated in that tutorial are used here.
 
 The Artifact API is a Python 3 application programming interface (API) for QIIME 2. The Artifact API supports interactive computing with QIIME 2 using the Python 3 programming language. This API is intended for advanced/technical users. The API is automatically generated, and its availability depends on which QIIME 2 plugins are currently installed. It has been optimized for use in the `Jupyter Notebook`_, which is currently our primary target for use of this API. The Artifact API is a part of the QIIME 2 framework; no additional software needs to be installed to use it.
diff --git a/source/interfaces/index.rst b/source/interfaces/index.rst
@@ -1,6 +1,8 @@
 Interfaces
 ==========
 
+.. include:: ../_old_docs_warning.rst
+
 .. toctree::
    :maxdepth: 2
 
diff --git a/source/interfaces/q2cli.rst b/source/interfaces/q2cli.rst
@@ -1,6 +1,8 @@
 QIIME 2 command-line interface (q2cli)
 ======================================
 
+.. include:: ../_old_docs_warning.rst
+
 .. note:: This guide assumes you have installed the QIIME 2 Amplicon distribution using one of the procedures in the :doc:`install documents <../install/index>`.
 
 This guide provides an introduction to ``q2cli``, a QIIME 2 command-line interface included in each of the available QIIME 2 distributions. The :doc:`tutorials <../tutorials/index>` use ``q2cli`` extensively, so it is recommended to review this document first before beginning the tutorials. This document is a work-in-progress and will be expanded in the future.
diff --git a/source/jupyter-book-tutorials.rst b/source/jupyter-book-tutorials.rst
@@ -1,6 +1,8 @@
 Jupyter Book Tutorials
 ============================
 
+.. include:: _old_docs_warning.rst
+
 These tutorials are powered by `Jupyter Book <https://jupyterbook.org/intro.html>`_,
 a Jupyter-based documentation tool developed with support from the
 `Sloan Foundation <https://sloan.org/grant-detail/9231>`_.
diff --git a/source/plugins/developing.rst b/source/plugins/developing.rst
@@ -1,7 +1,9 @@
 Developing a QIIME 2 plugin
 ===========================
 
-.. note:: This document is a work in progress, and serves as basic instructions for creating a QIIME 2 plugin. You can also find some (very preliminary) developer documentation at `https://dev.qiime2.org <https://dev.qiime2.org/latest/>`__.
+.. include:: ../_old_docs_warning.rst
+
+.. note:: This content is outdated. Instead, please refer to https://develop.qiime2.org.
 
 Creating a QIIME 2 plugin allows you to provide microbiome analysis functionality to QIIME 2 users. A plugin can be a standalone software project, or you can make a few small additions to your existing software project to make it a QIIME 2 plugin. Creating a single QIIME 2 plugin will make your functionality accessible through any QIIME 2 interface, including the :doc:`q2cli <../interfaces/q2cli>`, and the :doc:`Artifact API <../interfaces/artifact-api>`.
 
diff --git a/source/plugins/future.rst b/source/plugins/future.rst
@@ -1,9 +1,10 @@
 Future plugins
 ==============
 
+.. include:: ../_old_docs_warning.rst
+
 Plugins planned for future releases and non-core plugins are discussed in the `QIIME 2 Forum`_. If you have questions about the availability of QIIME 2 methods, actions, pipelines, or plugins, please post your questions there. If you are working on a plugin that is not part of an existing QIIME 2 distribution, but you'd like to inform QIIME 2 users about it, you should post a topic to the `Community Plugins category`_ on the forum.
 
 If you're looking for documentation on how to develop a plugin, see :doc:`this guide <developing>`.
 
-.. _QIIME 2 Forum: https://forum.qiime2.org
 .. _Community Plugins category: https://forum.qiime2.org/c/community-plugins
diff --git a/source/plugins/index.rst b/source/plugins/index.rst
@@ -1,6 +1,8 @@
 Plugins
 =======
 
+.. include:: ../_old_docs_warning.rst
+
 The following pages describe what QIIME 2 plugins are available and how to develop a new plugin.
 
 .. toctree::
diff --git a/source/semantic-types.rst b/source/semantic-types.rst
@@ -1,6 +1,8 @@
 Semantic types
 ==============
 
+.. include:: _old_docs_warning.rst
+
 All QIIME 2 artifacts have defined semantic types. This document is a placeholder for full documentation of how to use these types and how to define new semantic types in QIIME 2 plugins.
 
 Why define semantic types?
diff --git a/source/supplementary-resources.rst b/source/supplementary-resources.rst
@@ -1,6 +1,8 @@
 Supplementary resources
 =======================
 
+.. include:: _old_docs_warning.rst
+
 Educational content
 -------------------
 
diff --git a/source/tutorials/atacama-soils.rst b/source/tutorials/atacama-soils.rst
@@ -1,6 +1,8 @@
 "Atacama soil microbiome" tutorial
 ==================================
 
+.. include:: ../_old_docs_warning.rst
+
 .. note:: This guide assumes you have installed QIIME 2 using one of the
    procedures in the :doc:`install documents <../install/index>` and completed
    the :doc:`moving pictures tutorial <moving-pictures>`.
diff --git a/source/tutorials/chimera.rst b/source/tutorials/chimera.rst
@@ -1,6 +1,8 @@
 Identifying and filtering chimeric feature sequences with q2-vsearch
 ====================================================================
 
+.. include:: ../_old_docs_warning.rst
+
 Chimera checking in QIIME 2 is performed on a pair of ``FeatureTable[Frequency]`` and ``FeatureData[Sequences]`` artifacts. QIIME 2 wraps the Uchime *de novo* and reference pipelines from vsearch. For details on how these work, see the original `Uchime paper`_, and the `vsearch`_ documentation.
 
 In this tutorial, we'll use the table and sequences from the :doc:`Atacama soils tutorial <atacama-soils>`.
diff --git a/source/tutorials/exporting.rst b/source/tutorials/exporting.rst
@@ -1,6 +1,8 @@
 Exporting data
 ==============
 
+.. include:: ../_old_docs_warning.rst
+
 .. note:: This tutorial assumes you have installed QIIME 2 using one of the procedures in the :doc:`install documents <../install/index>`.
 
 In order to use QIIME 2, your input data must be stored in *QIIME 2 artifacts* (i.e. ``.qza`` files). This is what enables distributed and automatic provenance tracking, as well as semantic type validation and transformations between data formats (see the :doc:`core concepts <../concepts>` page for more details about QIIME 2 artifacts).
diff --git a/source/tutorials/feature-classifier.rst b/source/tutorials/feature-classifier.rst
@@ -1,6 +1,8 @@
 Training feature classifiers with q2-feature-classifier
 =======================================================
 
+.. include:: ../_old_docs_warning.rst
+
 .. note:: This guide assumes you have installed QIIME 2 using one of the procedures in the :doc:`install documents <../install/index>`.
 
 This tutorial will demonstrate how to train ``q2-feature-classifier`` for a particular dataset. We will train the `Naive Bayes`_ classifier using `Greengenes`_ reference sequences and classify the representative sequences from the `Moving Pictures`_ dataset.
@@ -111,7 +113,6 @@ In our experience, fungal ITS classifiers trained on the `UNITE reference databa
 
 
 .. _Moving Pictures: ../moving-pictures/index.html
-.. _QIIME 2 forum: https://forum.qiime2.org/c/community-contributions/data-resources
 .. _Naive Bayes: http://scikit-learn.org/stable/modules/naive_bayes.html#multinomial-naive-bayes
 .. _Greengenes: http://qiime.org/home_static/dataFiles.html
 .. _(Werner et al., 2012): https://www.ncbi.nlm.nih.gov/pubmed/21716311
diff --git a/source/tutorials/filtering.rst b/source/tutorials/filtering.rst
@@ -1,6 +1,8 @@
 Filtering data
 ==============
 
+.. include:: ../_old_docs_warning.rst
+
 .. note:: This guide assumes you have installed QIIME 2 using one of the procedures in the :doc:`install documents <../install/index>`.
 
 This tutorial describes how to filter feature tables, sequences, and distance matrices in QIIME 2, and will be expanded as more filtering functionality becomes available.
diff --git a/source/tutorials/fmt.rst b/source/tutorials/fmt.rst
@@ -1,6 +1,8 @@
 Fecal microbiota transplant (FMT) study: an exercise
 ====================================================
 
+.. include:: ../_old_docs_warning.rst
+
 .. note:: This guide assumes you have installed QIIME 2 using one of the procedures in the :doc:`install guides <../install/index>`.
 
 This document is intended to be run after :doc:`the moving pictures tutorial <moving-pictures>`. It is designed to introduce a few new ideas, and to be an exercise in applying the tools that were explored in that document.
diff --git a/source/tutorials/importing.rst b/source/tutorials/importing.rst
diff --git a/source/tutorials/index.rst b/source/tutorials/index.rst
diff --git a/source/tutorials/longitudinal.rst b/source/tutorials/longitudinal.rst
diff --git a/source/tutorials/metadata.rst b/source/tutorials/metadata.rst
diff --git a/source/tutorials/moving-pictures-usage.rst b/source/tutorials/moving-pictures-usage.rst
diff --git a/source/tutorials/moving-pictures.rst b/source/tutorials/moving-pictures.rst
diff --git a/source/tutorials/otu-clustering.rst b/source/tutorials/otu-clustering.rst
diff --git a/source/tutorials/overview.rst b/source/tutorials/overview.rst
diff --git a/source/tutorials/pd-mice.rst b/source/tutorials/pd-mice.rst
diff --git a/source/tutorials/phylogeny.rst b/source/tutorials/phylogeny.rst
diff --git a/source/tutorials/qiime2-for-experienced-microbiome-researchers.rst b/source/tutorials/qiime2-for-experienced-microbiome-researchers.rst
diff --git a/source/tutorials/quality-control.rst b/source/tutorials/quality-control.rst
diff --git a/source/tutorials/read-joining.rst b/source/tutorials/read-joining.rst
diff --git a/source/tutorials/sample-classifier.rst b/source/tutorials/sample-classifier.rst
diff --git a/source/tutorials/utilities.rst b/source/tutorials/utilities.rst

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. include:: ../../../_old_docs_warning.rst`
	`2`	`+`
`1`	`3`	`{{ title }}`
`2`	`4`	`{{ '=' * title\|length }}`
`3`	`5`