From 83bf2b0de325894032a7df0cada5e1e8273541e2 Mon Sep 17 00:00:00 2001 From: Greg Caporaso <192372+gregcaporaso@users.noreply.github.com> Date: Sat, 11 May 2024 07:27:42 -0700 Subject: [PATCH] transfer content based on re-assessment of where it belongs (#107) --- book/_toc.yml | 15 +++++---------- book/ci/how-to-guides/intro.md | 5 ----- book/ci/intro.md | 11 ++++------- book/ci/tutorials/intro.md | 5 ----- .../how-to-guides}/distribute-on-gh.md | 5 ++--- .../how-to-guides/maximize-compatibility.md | 4 ++-- book/{ci => plugins}/how-to-guides/publicize.md | 6 +++--- .../how-to-guides/support-your-users.md | 2 +- 8 files changed, 17 insertions(+), 36 deletions(-) delete mode 100644 book/ci/how-to-guides/intro.md delete mode 100644 book/ci/tutorials/intro.md rename book/{ci/tutorials => plugins/how-to-guides}/distribute-on-gh.md (93%) rename book/{ci => plugins}/how-to-guides/maximize-compatibility.md (92%) rename book/{ci => plugins}/how-to-guides/publicize.md (96%) rename book/{ci => plugins}/how-to-guides/support-your-users.md (97%) diff --git a/book/_toc.yml b/book/_toc.yml index 1764b5b..cc58743 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -22,6 +22,10 @@ parts: - file: plugins/how-to-guides/intro sections: - file: plugins/how-to-guides/set-up-development-environment + - file: plugins/how-to-guides/distribute-on-gh + - file: plugins/how-to-guides/support-your-users + - file: plugins/how-to-guides/maximize-compatibility + - file: plugins/how-to-guides/publicize - file: plugins/how-to-guides/register-a-plugin - file: plugins/how-to-guides/create-register-method - file: plugins/how-to-guides/create-register-visualizer @@ -32,7 +36,7 @@ parts: - file: plugins/how-to-guides/use-metadata - file: plugins/how-to-guides/test-plugins - file: plugins/how-to-guides/usage-examples - - file: plugins/how-to-guides/format-validation-levels.md + - file: plugins/how-to-guides/format-validation-levels - file: plugins/explanations/intro sections: - file: plugins/explanations/actions @@ -85,15 +89,6 @@ parts: - caption: "Continuous Integration 🛠️" chapters: - file: ci/intro - sections: - - file: ci/tutorials/intro - sections: - - file: ci/tutorials/distribute-on-gh - - file: ci/how-to-guides/intro - sections: - - file: ci/how-to-guides/support-your-users - - file: ci/how-to-guides/publicize - - file: ci/how-to-guides/maximize-compatibility - caption: "Back Matter 🗂️" chapters: diff --git a/book/ci/how-to-guides/intro.md b/book/ci/how-to-guides/intro.md deleted file mode 100644 index 6c24d12..0000000 --- a/book/ci/how-to-guides/intro.md +++ /dev/null @@ -1,5 +0,0 @@ -(ci-how-to-intro)= -# How-To Guides - -```{tableofcontents} -``` \ No newline at end of file diff --git a/book/ci/intro.md b/book/ci/intro.md index 34a9627..3cd32c0 100644 --- a/book/ci/intro.md +++ b/book/ci/intro.md @@ -2,19 +2,16 @@ # Distribution Development ```{note} -This Part of DWQ2 is in early development. +This Part of DWQ2 is in early development, and currently provides references to relevant content in other Parts of *Developing with QIIME 2*. We're open to feedback on the ideas presented here, and some technical details may change as the ideas develop. ``` You don't need approval from existing QIIME 2 developers to create and distribute your own tools, such as plugins or interfaces, that build on QIIME 2. -This is the beauty of [plugin-based, interface-agnostic architecture](q2-architecture-overview): new functionality can be introduced by anyone, removing bottlenecks or gatekeepers between developers and users. +This is the beauty of [plugin-based, interface-agnostic architecture](q2-architecture-overview): new functionality or new ways to use that functionality can be introduced by anyone, removing bottlenecks or gatekeepers between developers and users. Customized QIIME 2 distributions can also be created and shared by anyone. As of this writing (23 April 2024) we are redesigning our approach to helping you share and promote your QIIME 2-based tools. -[](share-on-github) provides an example of how you can currently share your tools with users, and we are actively working to expand that functionality to make it more useful for developers and users. -We also discuss more general ideas on sharing QIIME 2-based tools in [](ci-how-to-publicize). +[](share-on-github) provides an example of how you can currently share your plugin with users, and we are actively working to expand that functionality to make it more useful for developers and users. +We also discuss more general ideas on sharing QIIME 2-based tools in [](plugin-how-to-publicize). As our support in this area improves, this Part of *Developing with QIIME 2* will be expanded to describe new functionality. - -```{tableofcontents} -``` \ No newline at end of file diff --git a/book/ci/tutorials/intro.md b/book/ci/tutorials/intro.md deleted file mode 100644 index 72ec397..0000000 --- a/book/ci/tutorials/intro.md +++ /dev/null @@ -1,5 +0,0 @@ -(ci-tutorial-intro)= -# Tutorials - -```{tableofcontents} -``` \ No newline at end of file diff --git a/book/ci/tutorials/distribute-on-gh.md b/book/plugins/how-to-guides/distribute-on-gh.md similarity index 93% rename from book/ci/tutorials/distribute-on-gh.md rename to book/plugins/how-to-guides/distribute-on-gh.md index d763e6f..97438fa 100644 --- a/book/ci/tutorials/distribute-on-gh.md +++ b/book/plugins/how-to-guides/distribute-on-gh.md @@ -1,5 +1,5 @@ (share-on-github)= -# Distributing plugins on GitHub +# Distribute plugins on GitHub GitHub is a straight-forward way to share your QIIME 2 plugin. This tutorial will walk you through creating a QIIME 2 plugin from template, and then sharing it with installation instructions on GitHub. @@ -76,6 +76,5 @@ Here are some tips related to updating the installation instructions for your pl - Be sure to update the `README.md` if you introduce any new constraints (e.g., that your plugin can only be installed on Linux). It's fine to do that, but you should let your users know so they don't get grumpy about your plugin. -If you're ready to start getting users, the next steps are helping prospective users discover your plugin, and supporting them as they learn to use it. -We have some suggestions on those topics and others in this Part's [](ci-how-to-intro). +If you're ready to start getting users, the next steps are [helping prospective users discover your plugin](plugin-how-to-publicize), and [supporting them as they use it](plugin-how-to-support-your-users). diff --git a/book/ci/how-to-guides/maximize-compatibility.md b/book/plugins/how-to-guides/maximize-compatibility.md similarity index 92% rename from book/ci/how-to-guides/maximize-compatibility.md rename to book/plugins/how-to-guides/maximize-compatibility.md index 77a003a..87ef537 100644 --- a/book/ci/how-to-guides/maximize-compatibility.md +++ b/book/plugins/how-to-guides/maximize-compatibility.md @@ -1,4 +1,4 @@ -(ci-how-to-maximize-compatibility)= +(plugin-how-to-maximize-compatibility)= # Maximize compatibility between your plugin(s) and existing QIIME 2 distribution(s) You can build your QIIME 2 tools in your own way. @@ -11,7 +11,7 @@ A complete list of artifact classes and formats available in a deployment of QII (Some are missing documentation - we'd [love your help addressing that](https://github.com/caporaso-lab/developing-with-qiime2/issues/97).) If you do need to create new artifact classes, you can add these in your own plugin(s). -The Caporaso Lab is not taking on new responsibility for distributing plugins right now (i.e., integrating them in the distributions they develop and maintain), but we are curently (23 April 2024) developing new mechanisms for helping you share your plugin or other tools (see [](ci-how-to-publicize)) that will ultimately replace the [QIIME 2 Library](https://library.qiime2.org). +The Caporaso Lab is not taking on new responsibility for distributing plugins right now (i.e., integrating them in the distributions they develop and maintain), but we are currently (23 April 2024) developing new mechanisms for helping you share your plugin or other tools (see [](plugin-how-to-publicize)) that will ultimately replace the [QIIME 2 Library](https://library.qiime2.org). You can consider the existing distributions to be foundations that you can build on, or you can create and distribute your own conda metapackages. Some guidance on each of these approaches: diff --git a/book/ci/how-to-guides/publicize.md b/book/plugins/how-to-guides/publicize.md similarity index 96% rename from book/ci/how-to-guides/publicize.md rename to book/plugins/how-to-guides/publicize.md index 920b531..236a508 100644 --- a/book/ci/how-to-guides/publicize.md +++ b/book/plugins/how-to-guides/publicize.md @@ -1,7 +1,7 @@ -(ci-how-to-publicize)= -# Publicize your QIIME 2 tools +(plugin-how-to-publicize)= +# Publicize your QIIME 2 plugins (or other QIIME 2-based tools) -If you want others to use your QIIME 2 tools, you have to market them. +If you want others to use your QIIME 2-based tools, such as plugins, you have to market them. Ultimately that's your responsibility - **you** built it, **you** know it, **you're** proud of it, so **you need to promote it**. Here are some ideas on how to market your tools. diff --git a/book/ci/how-to-guides/support-your-users.md b/book/plugins/how-to-guides/support-your-users.md similarity index 97% rename from book/ci/how-to-guides/support-your-users.md rename to book/plugins/how-to-guides/support-your-users.md index f815439..b2903cf 100644 --- a/book/ci/how-to-guides/support-your-users.md +++ b/book/plugins/how-to-guides/support-your-users.md @@ -1,4 +1,4 @@ -(ci-how-to-support-your-users)= +(plugin-how-to-support-your-users)= # Provide technical support for your users You are free to have your users request help on the [QIIME 2 Forum](https://forum.qiime2.org) for your QIIME 2-based tools.