User documentation

User documentation#

As of the time of this writing (12 January 2023) the QIIME 2 user documentation is in a state of transition. This document presents ideas about where we’re planning to go with the user documentation in the future and then covers how to contribute to the current user documentation (https://docs.qiime2.org)

Plans for refactoring of user documentation#

We are moving from a single source of documentation (the current content at https://docs.qiime2.org) to resources for cross-distribution QIIME 2 documentation, within-distribution QIIME 2 reference material, and data set specific usage documentation.

We expect that the cross-distribution user documentation will cover topics including:

  • building and use a cache, which will expand on the content here

  • parallel support, which will expand on the content here

  • provenance replay/viewing, which will expand on the content here

  • using the interfaces

  • recycling old results

  • installing old versions of QIIME 2 (why, why not, and how)

  • discussion of distributions (why are there multiple? how to deal with that)

  • importing/exporting

  • viewing .qzvs

Distribution specific reference material will likely be the equivalent of our current plugin/action pages. These will render all usage examples associated with actions as well, to avoid the need for things like the “filtering tutorial” (which isn’t really a tutorial, but rather a list of different approaches for filtering data). Ideally generation of distribution-specific reference documentation will be fully automated, such that these docs can be built from any QIIME 2 environment using the PluginManager.

Usage tutorials, like the Moving Pictures tutorial, will be dataset specific and may cross distributions (like the Cancer Microbiome Intervention Tutorial). This will facilitate the transition from replayed provenance to tutorial, ideally helping to blur the line between replayed provenance and a tutorial over time. To support this, we will likely add a usage driver that generates usage driver source code (for example, select View Source (qiime2.sdk) from a multi-interface tutorial, so this can template documentation.

Contributing to the current user documentation#

Warning

These instructions are a little sparse at the moment and don’t cover things like working on your own fork or branch of the documentation. We do recommend forking and working on your own change-specific branch.

First, install the most recent release version of the QIIME 2 Amplicon Distribution, or create a QIIME 2 Amplicon Distribution development environment. Switch to that new environment.

Then, clone the QIIME 2 User documentation repository and install its requirements.

git clone https://github.com/qiime2/docs.git
cd docs
pip install -r requirements.txt

Build the documentation in preview mode to confirm that the build works before making your changes.

Note

Building the documentation in preview mode will avoid running all of the QIIME 2 steps covered in the tutorials during the build of the documentation, which will be vastly faster than doing a complete build (i.e., make html) of the documentation.

make preview

Make your edits, and re-build and view them. Iterate on this process until you’re done.

make preview
cd build/preview && python -m http.server ; cd -

The above command will launch a web server on your computer. Open http://localhost:8000/ in your browser to view the documentation as hosted on that local web server.

When you’re ready, submit a pull request in the usual way.