-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
add instructions for contributing to user docs
- Loading branch information
1 parent
5bca744
commit 23d0246
Showing
5 changed files
with
64 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
# Contributing to the QIIME 2 developer documentation |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,60 @@ | ||
# Contributing to the QIIME 2 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 covers how to contribute to the current user documentation (https://docs.qiime2.org), and presents some ideas about where we're planning to go with the user documentation in the future. | ||
|
||
## 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](setup-dev-environment). Switch to that new environment. | ||
|
||
Then, clone the QIIME 2 User documentation repository and install its requirements. | ||
|
||
```bash | ||
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. | ||
``` | ||
|
||
```bash | ||
make preview | ||
``` | ||
|
||
Make your edits, and re-build and view them. Iterate on this process until you're done. | ||
|
||
```bash | ||
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. | ||
|
||
## 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](https://forum.qiime2.org/t/qiime-2-2022-11-is-now-available/25074#artifact-cachehttpsdevqiime2orglatestapi-referencecache-3) | ||
- parallel support | ||
- provenance replay/viewing, which will expand on the [content here](https://forum.qiime2.org/t/provenance-replay-beta-release-and-tutorial/23279) | ||
- 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](https://docs.qiime2.org/2023.9/plugins/). These will render all usage examples associated with actions as well, to avoid the need for things like the ["filtering tutorial"](https://docs.qiime2.org/2023.9/tutorials/filtering/) (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](https://docs.qiime2.org/2023.9/tutorials/moving-pictures-usage/), will be dataset specific and may cross distributions (like the [Cancer Microbiome Intervention Tutorial](https://docs.qiime2.org/jupyterbooks/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](https://docs.qiime2.org/2023.9/tutorials/moving-pictures-usage/), so this can template documentation. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters