Merge pull request #5 from caporaso-lab/2024.5.beta-release-update

REL: release version of documentation

book/index.md

@@ -7,9 +7,9 @@ q2-boots is a [QIIME 2](https://qiime2.org) plugin providing bootstrapped and ra
 q2-boots is in beta release. It is sufficiently validated and ready for real-world data analysis, but **interfaces are still subject to change**. For example, default parameter settings, command names, and outputs generated by specific commands may evolve as we get usability feedback and feature requests from users.
 ```
 
-## Installation
+## Installing
 
-### Install Prerequisites
+### Step 1: Install prerequisites
 
 {{ miniconda_url }} provides the `conda` environment and package manager, and is currently the only supported way to install QIIME 2.
 Follow the instructions for downloading and installing Miniconda.
@@ -20,19 +20,42 @@ After installing Miniconda and opening a new terminal, make sure you're running
 conda update conda
 ```
 
-### QIIME 2024.10 development version of q2-boots
+### Step 2: Install q2-boots
 
-Installing the most recent development version of q2-boots allows you to access the most recent functionality, including some that depends on features being introduced in QIIME 2 2024.10.
+`````{tab-set}
+````{tab-item} 2024.5.beta release
+Installing the release version of q2-boots allows you to access the most stable version of the functionality in a QIIME 2 2024.5 release environment.
+This is most convenient if you need to reference a specific version of q2-boots in a publication (you would refer to it as the *2024.5.beta release of q2-boots*.)
+Since q2-boots is still under active development, there may be some new functionality that isn't included in this release.
 
 ```shell
-conda env create -n q2-boots-2024.10 -f https://raw.githubusercontent.com/qiime2/q2-boots/main/environments/q2-boots-qiime2-amplicon-2024.10.yml
+conda env create \
+  -n q2-boots-2024.5.beta \
+  -f https://raw.githubusercontent.com/qiime2/q2-boots/main/environments/q2-boots-qiime2-amplicon-2024.5.yml
 ```
 
 ```shell
-conda activate q2-boots-2024.10
+conda activate q2-boots-2024.5.beta
 ```
+````
 
-## Using `q2-boots`
+````{tab-item} Latest development version
+Installing the most recent development version of q2-boots allows you to access the most recent functionality, including some that depends on features being introduced in the 2024.10 version of the QIIME 2 Framework. 🔧
+Referencing specific versions of q2-boots is still possible --- just be sure to hang on to your QIIME 2 `Results` and/or `Visualizations`, so you can review the specific revisions (including git commit hashes) in your data provenance.
+
+```shell
+conda env create \
+  -n q2-boots-2024.10.dev \
+  -f https://raw.githubusercontent.com/qiime2/q2-boots/main/environments/q2-boots-qiime2-amplicon-2024.10.yml
+```
+
+```shell
+conda activate q2-boots-2024.10.dev
+```
+````
+`````
+
+## Using
 
 After completing the install steps above, you can review the top-level q2-boots help text by running:
 
@@ -47,7 +70,8 @@ qiime boots core-metrics --help
 ```
 
 This will display the help text for the `core-metrics` command.
-Calling `core-metrics` with the `--example-data` parameter will write example data to the directory of your choosing.
+Notice the usage examples at the bottom of the help text - these are a good starting point for your commands.
+Calling `core-metrics` with the `--example-data` parameter will write the corresponding example data to a directory you specify for you to test or experiment with as you figure out how you want to use the command.
 For example:
 
 ```shell
@@ -71,18 +95,32 @@ Notice that the subdirectory names align with names of the usage examples in the
 Change into one of those directories and run the corresponding usage example to test out the command.
 You can then adapt the usage example commands to apply to your own data.
 
+Once you've figured out how you want to use q2-boots on your data, you can run `Pipelines` in parallel by including the `--parallel` flag in your commands:
+
+```shell
+qiime boots core-metrics --parallel ...
+```
+
+Pipeline resumption will work in the background, unless you pass `--no-recycle`, allowing you to restart failed runs without needing to recompute results that had already completed.
+
+```{note}
+The default parallel configuration changed between versions 2024.5 and 2024.10 of the QIIME 2 Framework.
+Parallel configuration will require a little more setup in the 2024.5.beta release of q2-boots - reach out on the QIIME 2 Forum if you're interested in doing this and we'll help out.
+If you're using the `--parallel` option with the 2024.10 development release of QIIME 2, you're all set.
+```
+
 Have fun! 😎
 
 ## Getting help
 
 If you need help with q2-boots, please get in touch on the [QIIME 2 Forum](https://forum.qiime2.org).
 
-## About
+## About `q2-boots`
 
 `q2-boots` was developed for a Master’s degree in Computer Science project at [Northern Arizona University (NAU)](https://www.nau.edu), and will be maintained by the [Caporaso Lab](https://cap-lab.bio) at NAU.
 
-The `q2-boots` Python package was built using content from the [QIIME 2 plugin template](https://develop.qiime2.org/en/latest/plugins/tutorials/create-from-template.html).
-To learn more about `q2-boots`, refer to the [project website](https://github.com/caporaso-lab/q2-boots).
+`q2-boots` was derived from content in the [QIIME 2 plugin template](https://develop.qiime2.org/en/latest/plugins/tutorials/create-from-template.html) (q2-boots existed before the plugin template, so didn't use it directly).
+To learn how to use `q2-boots`, refer to the [plugin documentation](https://q2-boots.readthedocs.io/en/latest/).
 To learn how to use QIIME 2, refer to the [QIIME 2 User Documentation](https://docs.qiime2.org).
 To learn QIIME 2 plugin development, refer to [*Developing with QIIME 2*](https://develop.qiime2.org).
 

book/requirements.txt

@@ -1 +1,2 @@
 jupyter-book
+sphinxcontrib.mermaid