diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..4830ba9e --- /dev/null +++ b/Makefile @@ -0,0 +1,21 @@ +.PHONY: lint install html clean cacheclean + +lint: + jupyter book build book/ \ + --warningiserror \ + --nitpick \ + --keep-going \ + --all \ + --verbose + +install: + pip install -r requirements.txt + +html: + jupyter book build book/ + +clean: + jupyter book clean book/ + +cacheclean: + rm -rf book/_build/ \ No newline at end of file diff --git a/book/00-intro.md b/book/00-intro.md deleted file mode 100644 index 434ede30..00000000 --- a/book/00-intro.md +++ /dev/null @@ -1,19 +0,0 @@ -# Developing with QIIME 2 - -*Developing with QIIME 2* is designed to help you develop software with QIIME 2. - -```{tableofcontents} -``` - -## Citing QIIME 2 and its dependencies - -QIIME 2 plugins frequently utilize other software packages that must be cited in addition to QIIME 2 itself. -QIIME 2 provides *citation reports* to help you ensure that you cite all relevant software. -Citation reports can be generated either by: - * running `qiime tools citations` on an Artifact or Visualization, or - * listing citations with [QIIME 2 View][q2view]. - To view the list of citations for a QIIME 2 Artifact or Visualization, load your result at [QIIME 2 View][q2view] and then navigate to the "Details" tab. - -QIIME 2 itself should be cited with the linked citation {cite}`qiime2-2019`. The easiest way to access that citation is by generating one of the citation reports mentioned above. - -[q2view]: https://view.qiime2.org \ No newline at end of file diff --git a/book/10-tutorial/00-intro.md b/book/10-tutorial/00-intro.md deleted file mode 100644 index 60b6d78b..00000000 --- a/book/10-tutorial/00-intro.md +++ /dev/null @@ -1,3 +0,0 @@ -# Introduction - -In this section, step-by-step instructions are provided for building your first QIIME 2 plugin and QIIME 2 interface. \ No newline at end of file diff --git a/book/10-tutorial/10-plugins/00-intro.rst b/book/10-tutorial/10-plugins/00-intro.rst deleted file mode 100644 index a8ae8460..00000000 --- a/book/10-tutorial/10-plugins/00-intro.rst +++ /dev/null @@ -1,262 +0,0 @@ -Building your first 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 `__. - -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 command line interface and the Python 3 API. - -Overview --------- - -There are several high-level steps to creating a QIIME 2 plugin: - -1. A QIIME 2 plugin must define one or more Python 3 functions that will be accessible through QIIME. The plugin must be a Python 3 package that can be installed with ``setuptools``. -2. The plugin must then instantiate a ``qiime2.plugin.Plugin`` object and define some information including the name of the plugin and its URL. In the plugin package's ``setup.py`` file, this instance will be defined as an entry point. -3. The plugin must then register its functions as QIIME 2 ``Actions``, which will be accessible to users through any of the QIIME 2 interfaces. -4. Optionally, the plugin should be distributed through `Anaconda`_, as that will simplify its installation for QIIME 2 users (since that is the supported mechanism for installing QIIME 2). - -These steps are covered in detail below. - -Writing a simple QIIME 2 plugin should be a straightforward process. For example, the `q2-emperor`_ plugin, which connects `Emperor`_ to QIIME 2, is written in only around 100 lines of code. It is a standalone plugin that defines how and which functionality in Emperor should be accessible through QIIME 2. Plugins will vary in their complexity. For example, a plugin that defines a lot of new functionality would likely be quite a bit bigger. `q2-diversity`_ is a good example of this. Unlike ``q2-emperor``, there is some specific functionality (and associated unit tests) defined in this project, and it depends on several other Python 3 compatible libraries. - -Before starting to write a plugin, you should install QIIME 2 and some plugins to familiarize yourself with the system and to provide a means for testing your plugin. - -Plugin components ------------------ - -The following discussion will refer to the `q2-diversity`_ plugin as an example. This plugin can serve as a reference as you define your own QIIME 2 plugins. - -.. note:: **QIIME 2 does not place restrictions on how a plugin package is structured.** The `q2-diversity`_ plugin is however a good representative of the conventions present in many of the initial QIIME 2 plugins. This package structure is simply a recommendation and a starting point for developing your own plugin; feel free to deviate from this structure as necessary or desired. - -Define functionality -++++++++++++++++++++ - -QIIME 2 users will access your functionality as QIIME 2 ``Actions``. These ``Actions`` can be either ``Methods`` or ``Visualizers``. A ``Method`` is an operation that takes some combination of ``Artifacts`` and ``Parameters`` as input, and produces one or more ``Artifacts`` as output. These output ``Artifacts`` could subsequently be used as input to other QIIME 2 ``Methods`` or ``Visualizers``. A ``Visualizer`` is an operation that takes some combination of ``Artifacts`` and ``Parameters`` as input, and produces exactly one ``Visualization`` as output. Output ``Visualizations``, by definition, cannot be used as input to other QIIME 2 ``Methods`` or ``Visualizers``. ``Methods`` therefore can produce intermediate or terminal output in a QIIME analysis, while ``Visualizers`` can only create terminal output. - -This section will describe how to define Python 3 functions that can be converted to QIIME 2 ``Methods`` or ``Visualizers``. These functions can be defined anywhere in your project; QIIME doesn't put restrictions on how your plugin package is structured. - -Create a function to register as a Method -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A function that can be registered as a ``Method`` will have a Python 3 API, and the inputs and outputs for that function will be annotated with their data types using `mypy`_ syntax. mypy annotation does not impact functionality (though the syntax is new to Python 3), so these can be added to existing functions in your Python 3 software project. An example is ``q2_diversity.beta_phylogenetic``, which takes a ``biom.Table``, an ``skbio.TreeNode`` and a ``str`` as input, and produces an ``skbio.DistanceMatrix`` as output. The signature for this function is: - -.. code-block:: python - - def beta_phylogenetic(table: biom.Table, phylogeny: skbio.TreeNode, - metric: str)-> skbio.DistanceMatrix: - -As far as QIIME is concerned, it doesn't matter what happens inside this function (as long as it adheres to the contract defined by the signature regarding the input and output types). For example, ``q2_diversity.beta_phylogenetic`` is making some calls to the ``skbio`` and ``biom`` APIs, but it could be doing anything, including making system calls (if your plugin is wrapping a command line application), executing an R library, etc. - -Create a function to register as a Visualizer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Defining a function that can be registered as a ``Visualizer`` is very similar to defining one that can be registered as a ``Method`` with a few additional requirements. - -First, the first parameter to this function must be ``output_dir``. This parameter should be annotated with type ``str``. - -Next, at least one ``index.*`` file must be written to ``output_dir`` by the function. This index file will provide the starting point for your users to explore the ``Visualization`` object that is generated by the ``Visualizer``. Index files with different extensions can be created by the function (e.g., ``index.html``, ``index.tsv``, ``index.png``), but at least one must be created. You can write whatever files you want to ``output_dir``, including tables, graphics, and textual descriptions of the results, but you should expect that your users will want to find those files through your index file(s). If your function does create many different files, an ``index.html`` containing links to those files is likely to be helpful. - -Finally, the function cannot return anything, and its return type should be annotated as ``None``. - -``q2_diversity.alpha_group_significance`` is an example of a function that can be registered as a ``Visualizer``. In addition to its ``output_dir``, it takes alpha diversity results in a ``pandas.Series`` and sample metadata in a ``qiime2.Metadata`` object and creates several different files (figures and tables) that are linked and/or presented in an ``index.html`` file. The signature of this function is: - -.. code-block:: python - - def alpha_group_significance(output_dir: str, alpha_diversity: pd.Series, - metadata: qiime2.Metadata) -> None: - -Instantiating a plugin -++++++++++++++++++++++ - -The next step is to instantiate a QIIME 2 ``Plugin`` object. This might look like the following: - -.. code-block:: python - - from qiime2.plugin import Plugin - import q2_diversity - - plugin = Plugin( - name='diversity', - version=q2_diversity.__version__, - website='https://qiime2.org', - user_support_text='https://forum.qiime2.org', - package='q2_diversity' - ) - -This will provide QIIME with essential information about your ``Plugin``. - -The ``name`` parameter is the name that users will use to access your plugin from within different QIIME 2 interfaces. It should be a "command line friendly" name, so should not contain spaces or punctuation. (Avoiding uppercase characters and using dashes (``-``) instead of underscores (``_``) are preferable in the plugin ``name``, but not required). - -``version`` should be the version number of your package (the same that is used in its ``setup.py``). - -``website`` should be the page where you'd like end users to refer for more information about your package. Since ``q2-diversity`` doesn't have its own website, we're including the QIIME 2 website here. - -``package`` should be the Python package name for your plugin. - -While not shown in the previous example, plugin developers can optionally provide the following parameters to ``qiime2.plugin.Plugin``: - -* ``citation_text``: free text describing how users should cite the plugin and/or the underlying tools it wraps. If not provided, users are told to cite the ``website``. - -* ``user_support_text``: free text describing how users should get help with the plugin (e.g. issue tracker, StackOverflow tag, mailing list, etc.). If not provided, users are referred to the ``website`` for support. ``q2-diversity`` is supported on the QIIME 2 Forum, so we include that URL here. We encourage plugin developers to support their plugins on the QIIME 2 Forum, so you can include that URL as the ``user_support_text`` for your plugin. If you do that, you should get in the habit of monitoring the QIIME 2 Forum for technical support questions. - -The ``Plugin`` object can live anywhere in your project, but by convention it will be in a file called ``plugin_setup.py``. For an example, see ``q2_diversity/plugin_setup.py``. - -Registering an Action -+++++++++++++++++++++ - -Once you have functions that you'd like to register as ``Actions`` (i.e., either ``Methods`` or ``Visualizers``), and you've instantiated your ``Plugin`` object, you are ready to register those functions. This will likely be done in the file where the ``Plugin`` object was instantiated, as it will use that instance (which will be referred to as ``plugin`` in the following examples). - -Registering a Method -~~~~~~~~~~~~~~~~~~~~ - -First we'll register a ``Method`` by calling ``plugin.methods.register_function`` as follows: - -.. code-block:: python - - from q2_types import (FeatureTable, Frequency, Phylogeny, - Rooted, DistanceMatrix) - from qiime2.plugin import Str, Choices, Properties, Metadata - - import q2_diversity - import q2_diversity._beta as beta - - plugin.methods.register_function( - function=q2_diversity.beta_phylogenetic, - inputs={'table': FeatureTable[Frequency], - 'phylogeny': Phylogeny[Rooted]}, - parameters={'metric': Str % Choices(beta.phylogenetic_metrics())}, - outputs=[('distance_matrix', DistanceMatrix % Properties('phylogenetic'))], - input_descriptions={ - 'table': ('The feature table containing the samples over which beta ' - 'diversity should be computed.'), - 'phylogeny': ('Phylogenetic tree containing tip identifiers that ' - 'correspond to the feature identifiers in the table. ' - 'This tree can contain tip ids that are not present in ' - 'the table, but all feature ids in the table must be ' - 'present in this tree.') - }, - parameter_descriptions={ - 'metric': 'The beta diversity metric to be computed.' - }, - output_descriptions={'distance_matrix': 'The resulting distance matrix.'}, - name='Beta diversity (phylogenetic)', - description=("Computes a user-specified phylogenetic beta diversity metric" - " for all pairs of samples in a feature table.") - ) - -The values being provided are: - -``function``: The function to be registered as a method. - -``inputs``: A dictionary indicating the parameter name and its *semantic type*, for each input ``Artifact``. These semantic types differ from the data types that you provided in your `mypy`_ annotation of the input, as semantic types describe the data, where the data types indicate the structure of the data. The currently available semantic types can be viewed by running ``qiime tools import --show-importable-types`` (until merge of `this PR `_, which will improve on how this information is accessed from the command line). In the example above we're indicating that the ``table`` parameter must be a ``FeatureTable`` of ``Frequency`` (i.e. counts), and that the ``phylogeny`` parameter must be a ``Phylogeny`` that is ``Rooted``. Notice that the keys in ``inputs`` map directly to the parameter names in ``q2_diversity.beta_phylogenetic``. - -``parameters``: A dictionary indicating the parameter name and its *semantic type*, for each input ``Parameter``. These parameters are primitive values (i.e., non-``Artifacts``). In the example above, we're indicating that the ``metric`` should be a string from a specific set (in this case, the set of known phylogenetic beta diversity metrics). - -``outputs``: A list of tuples indicating each output name and its semantic type. - -``input_descriptions``: A dictionary containing input artifact names and their corresponding descriptions. This information is used by interfaces to instruct users how to use each specific input artifact. - -``parameter_descriptions``: A dictionary containing parameter names and their corresponding descriptions. This information is used by interfaces to instruct users how to use each specific input parameter. You should not include any default parameter values in these descriptions, as these will generally be added automatically by an interface. - -``output_descriptions``: A dictionary containing output artifact names and their corresponding descriptions. This information is used by interfaces to inform users what each specific output artifact will be. - -``name``: A human-readable name for the ``Method``. This may be presented to users in interfaces. - -``description``: A human-readable description of the ``Method``. This may be presented to users in interfaces. - -Registering a Visualizer -~~~~~~~~~~~~~~~~~~~~~~~~ - -Registering ``Visualizers`` is the same as registering ``Methods``, with two exceptions. - -First, you call ``plugin.visualizers.register_function`` to register a ``Visualizer``. - -Next, you do not provide ``outputs`` or ``output_descriptions`` when making this call, as ``Visualizers``, by definition, only return a single visualization. Since the visualization output path is a required parameter, you do not include this in an ``outputs`` list (it would be the same for every ``Visualizer`` that was ever registered, so it is added automatically). - -Registering ``q2_diversity.alpha_group_significance`` as a ``Visualizer`` looks like the following: - -.. code-block:: python - - plugin.visualizers.register_function( - function=q2_diversity.alpha_group_significance, - inputs={'alpha_diversity': SampleData[AlphaDiversity]}, - parameters={'metadata': Metadata}, - input_descriptions={ - 'alpha_diversity': 'Vector of alpha diversity values by sample.' - }, - parameter_descriptions={ - 'metadata': 'The sample metadata.' - }, - name='Alpha diversity comparisons', - description=("Visually and statistically compare groups of alpha diversity" - " values.") - ) - -Defining your plugin object as an entry point -+++++++++++++++++++++++++++++++++++++++++++++ - -Finally, you need to tell QIIME where to find your instantiated ``Plugin`` object. This is done by defining it as an ``entry_point`` in your project's ``setup.py`` file. In ``q2-diversity``, this is done as follows: - -.. code-block:: python - - setup( - ... - entry_points={ - 'qiime2.plugins': ['q2-diversity=q2_diversity.plugin_setup:plugin'] - } - ) - -The relevant key in the ``entry_points`` dictionary will be ``'qiime2.plugins'``, and the value will be a single element list containing a string formatted as ``=:``. ```` is the name of the Python package distribution (matching the value passed for ``name`` in this call to ``setup``); ```` is the import path for the ``Plugin`` instance you created above; and ```` is the name for the ``Plugin`` instance you created above. - -Testing your plugin with q2cli during development -------------------------------------------------- - -If you are testing your plugin with ``q2cli`` (i.e. the ``qiime`` command) while you are developing it, you'll need to run ``qiime dev refresh-cache`` to see the latest changes to your plugin reflected in the command line interface (CLI). You'll need to run this command anytime you modify your plugin's interface (e.g. add/rename/remove a command or its inputs/parameters/outputs, and edit any of the plugin/action/input/parameter/output descriptions). - -Another option is to set the environment variable ``Q2CLIDEV=1`` so that the cache is refreshed every time a command is run. This will slow down the CLI while developing because refreshing the cache is slow. However, the CLI is much faster when a user installs release versions of QIIME 2 and plugins, so this slowdown should only be apparent when *developing* a plugin. - -This manual refreshing of the ``q2cli`` cache is necessary because it can't detect when changes are made to a plugin's code while under development (the plugin's version remains the same across code edits). This manual refreshing of the cache should only be necessary while developing a plugin; when users install QIIME 2 and your released plugin (i.e. no longer in development), the cache will automatically be updated when necessary. - -Plugin testing --------------- - -Many of the QIIME 2 plugins, including `q2-emperor`_ and `q2-diversity`_, have continuous integration (CI) configuration for `Travis-CI`_ in their software repositories. This allows for automated testing any time a change to the plugin code is committed on GitHub if Travis-CI is enabled on the plugin's software repository. Plugin CI testing generally includes ``flake8`` linting/style-checking and a ``nose`` or ``py.test`` command for running unit tests. - -Plugin developers are encouraged to add unit tests for their plugin's functionality, and to perform style checking with ``flake8``. Unit tests are an important part of determining if your software is working as expected, which will give you and your users confidence in the plugin. Adhering to a style convention, and checking that style with a tool like ``flake8``, is very helpful for others who want to understand your code, including users who want an in depth understanding of the functionality and potential open source software contributors. - -`Wilson et al. (2014)`_ present a good discussion of software testing and related topics that is very helpful for scientists who are beginning to develop and distribute software. - -Advanced plugin development ---------------------------- - -Defining semantic types, data layouts, and view readers/writers -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -This section is currently incomplete. In the meantime, if you have questions about these advanced plugin development topics, feel free to get in touch with us on the `forum`_. For an example of a plugin that define semantic types, data layouts, and view readers/writers, see `q2-types`_. - -Example plugins ---------------- - -* `q2-emperor`_: This is a simple plugin that is defined as a stand-alone package. It provides QIIME 2 access to functionality defined in `Emperor`_. - -* `q2-diversity`_: This is a more complex plugin, where the plugin is defined in the same package as the functionality that it's providing access to. - -* `q2-types`_: This is a more complex plugin defining real-world QIIME 2 types for bioinformatics/microbiome analyses. - -.. _`Anaconda`: https://anaconda.org/ - -.. _`q2-emperor`: https://github.com/qiime2/q2-emperor - -.. _`Emperor`: https://github.com/biocore/emperor - -.. _`q2-diversity`: https://github.com/qiime2/q2-diversity - -.. _`Travis-CI`: https://travis-ci.org/ - -.. _`mypy`: http://mypy-lang.org/ - -.. _`q2-types`: https://github.com/qiime2/q2-types - -.. _`forum`: https://forum.qiime2.org - -.. _`Wilson et al. (2014)`: http://journals.plos.org/plosbiology/article?id=10.1371/journal.pbio.1001745 diff --git a/book/10-tutorial/10-plugins/10-plugin-setup.rst b/book/10-tutorial/10-plugins/10-plugin-setup.rst deleted file mode 100644 index badfe4e7..00000000 --- a/book/10-tutorial/10-plugins/10-plugin-setup.rst +++ /dev/null @@ -1,35 +0,0 @@ -Instantiating the `qiime2.plugin.Plugin` object -############################################### - -The next step is to instantiate a QIIME 2 ``Plugin`` object. This might look like the following: - -.. code-block:: python - - from qiime2.plugin import Plugin - import q2_diversity - - plugin = Plugin( - name='diversity', - version=q2_diversity.__version__, - website='https://qiime2.org', - user_support_text='https://forum.qiime2.org', - package='q2_diversity' - ) - -This will provide QIIME with essential information about your ``Plugin``. - -The ``name`` parameter is the name that users will use to access your plugin from within different QIIME 2 interfaces. It should be a "command line friendly" name, so should not contain spaces or punctuation. (Avoiding uppercase characters and using dashes (``-``) instead of underscores (``_``) are preferable in the plugin ``name``, but not required). - -``version`` should be the version number of your package (the same that is used in its ``setup.py``). - -``website`` should be the page where you'd like end users to refer for more information about your package. Since ``q2-diversity`` doesn't have its own website, we're including the QIIME 2 website here. - -``package`` should be the Python package name for your plugin. - -While not shown in the previous example, plugin developers can optionally provide the following parameters to ``qiime2.plugin.Plugin``: - -* ``citation_text``: free text describing how users should cite the plugin and/or the underlying tools it wraps. If not provided, users are told to cite the ``website``. - -* ``user_support_text``: free text describing how users should get help with the plugin (e.g. issue tracker, StackOverflow tag, mailing list, etc.). If not provided, users are referred to the ``website`` for support. ``q2-diversity`` is supported on the QIIME 2 Forum, so we include that URL here. We encourage plugin developers to support their plugins on the QIIME 2 Forum, so you can include that URL as the ``user_support_text`` for your plugin. If you do that, you should get in the habit of monitoring the QIIME 2 Forum for technical support questions. - -The ``Plugin`` object can live anywhere in your project, but by convention it will be in a file called ``plugin_setup.py``. For an example, see ``q2_diversity/plugin_setup.py``. \ No newline at end of file diff --git a/book/10-tutorial/10-plugins/20-registering-actions.rst b/book/10-tutorial/10-plugins/20-registering-actions.rst deleted file mode 100644 index dd1452de..00000000 --- a/book/10-tutorial/10-plugins/20-registering-actions.rst +++ /dev/null @@ -1,95 +0,0 @@ -Registering an Action -##################### - -Once you have functions that you'd like to register as ``Actions`` (i.e., either ``Methods`` or ``Visualizers``), and you've instantiated your ``Plugin`` object, you are ready to register those functions. This will likely be done in the file where the ``Plugin`` object was instantiated, as it will use that instance (which will be referred to as ``plugin`` in the following examples). - -Registering a Method -++++++++++++++++++++ - -First we'll register a ``Method`` by calling ``plugin.methods.register_function`` as follows: - -.. code-block:: python - - from q2_types import (FeatureTable, Frequency, Phylogeny, - Rooted, DistanceMatrix) - from qiime2.plugin import Str, Choices, Properties, Metadata - - import q2_diversity - import q2_diversity._beta as beta - - plugin.methods.register_function( - function=q2_diversity.beta_phylogenetic, - inputs={'table': FeatureTable[Frequency], - 'phylogeny': Phylogeny[Rooted]}, - parameters={'metric': Str % Choices(beta.phylogenetic_metrics())}, - outputs=[('distance_matrix', DistanceMatrix % Properties('phylogenetic'))], - input_descriptions={ - 'table': ('The feature table containing the samples over which beta ' - 'diversity should be computed.'), - 'phylogeny': ('Phylogenetic tree containing tip identifiers that ' - 'correspond to the feature identifiers in the table. ' - 'This tree can contain tip ids that are not present in ' - 'the table, but all feature ids in the table must be ' - 'present in this tree.') - }, - parameter_descriptions={ - 'metric': 'The beta diversity metric to be computed.' - }, - output_descriptions={'distance_matrix': 'The resulting distance matrix.'}, - name='Beta diversity (phylogenetic)', - description=("Computes a user-specified phylogenetic beta diversity metric" - " for all pairs of samples in a feature table.") - ) - -The values being provided are: - -``function``: The function to be registered as a method. - -``inputs``: A dictionary indicating the parameter name and its *semantic type*, for each input ``Artifact``. These semantic types differ from the data types that you provided in your `mypy`_ annotation of the input, as semantic types describe the data, where the data types indicate the structure of the data. The currently available semantic types can be viewed by running ``qiime tools import --show-importable-types`` (until merge of `this PR `_, which will improve on how this information is accessed from the command line). In the example above we're indicating that the ``table`` parameter must be a ``FeatureTable`` of ``Frequency`` (i.e. counts), and that the ``phylogeny`` parameter must be a ``Phylogeny`` that is ``Rooted``. Notice that the keys in ``inputs`` map directly to the parameter names in ``q2_diversity.beta_phylogenetic``. - -``parameters``: A dictionary indicating the parameter name and its *semantic type*, for each input ``Parameter``. These parameters are primitive values (i.e., non-``Artifacts``). In the example above, we're indicating that the ``metric`` should be a string from a specific set (in this case, the set of known phylogenetic beta diversity metrics). - -``outputs``: A list of tuples indicating each output name and its semantic type. - -``input_descriptions``: A dictionary containing input artifact names and their corresponding descriptions. This information is used by interfaces to instruct users how to use each specific input artifact. - -``parameter_descriptions``: A dictionary containing parameter names and their corresponding descriptions. This information is used by interfaces to instruct users how to use each specific input parameter. You should not include any default parameter values in these descriptions, as these will generally be added automatically by an interface. - -``output_descriptions``: A dictionary containing output artifact names and their corresponding descriptions. This information is used by interfaces to inform users what each specific output artifact will be. - -``name``: A human-readable name for the ``Method``. This may be presented to users in interfaces. - -``description``: A human-readable description of the ``Method``. This may be presented to users in interfaces. - -Registering a Visualizer -++++++++++++++++++++++++ - -Registering ``Visualizers`` is the same as registering ``Methods``, with two exceptions. - -First, you call ``plugin.visualizers.register_function`` to register a ``Visualizer``. - -Next, you do not provide ``outputs`` or ``output_descriptions`` when making this call, as ``Visualizers``, by definition, only return a single visualization. Since the visualization output path is a required parameter, you do not include this in an ``outputs`` list (it would be the same for every ``Visualizer`` that was ever registered, so it is added automatically). - -Registering ``q2_diversity.alpha_group_significance`` as a ``Visualizer`` looks like the following: - -.. code-block:: python - - plugin.visualizers.register_function( - function=q2_diversity.alpha_group_significance, - inputs={'alpha_diversity': SampleData[AlphaDiversity]}, - parameters={'metadata': Metadata}, - input_descriptions={ - 'alpha_diversity': 'Vector of alpha diversity values by sample.' - }, - parameter_descriptions={ - 'metadata': 'The sample metadata.' - }, - name='Alpha diversity comparisons', - description=("Visually and statistically compare groups of alpha diversity" - " values.") - ) - -Registering a Pipeline -++++++++++++++++++++++ - -TODO: put a pipeline registration here diff --git a/book/10-tutorial/20-interfaces/00-intro.md b/book/10-tutorial/20-interfaces/00-intro.md deleted file mode 100644 index 805808ca..00000000 --- a/book/10-tutorial/20-interfaces/00-intro.md +++ /dev/null @@ -1 +0,0 @@ -# Building your first QIIME 2 interface \ No newline at end of file diff --git a/book/10-tutorial/20-interfaces/10-plugin-manager.md b/book/10-tutorial/20-interfaces/10-plugin-manager.md deleted file mode 100644 index 467d27d9..00000000 --- a/book/10-tutorial/20-interfaces/10-plugin-manager.md +++ /dev/null @@ -1 +0,0 @@ -# Instantiating `qiime2.sdk.PluginManager` \ No newline at end of file diff --git a/book/20-understanding/00-intro.md b/book/20-understanding/00-intro.md deleted file mode 100644 index 45e3ce49..00000000 --- a/book/20-understanding/00-intro.md +++ /dev/null @@ -1,3 +0,0 @@ -# Introduction - -This is a theoretical discussion of developing QIIME 2 plugins. \ No newline at end of file diff --git a/book/20-understanding/10-plugins/00-intro.md b/book/20-understanding/10-plugins/00-intro.md deleted file mode 100644 index 93a3c354..00000000 --- a/book/20-understanding/10-plugins/00-intro.md +++ /dev/null @@ -1 +0,0 @@ -# Understanding QIIME 2 Plugins \ No newline at end of file diff --git a/book/20-understanding/10-plugins/10-plugin.md b/book/20-understanding/10-plugins/10-plugin.md deleted file mode 100644 index 6e7620fe..00000000 --- a/book/20-understanding/10-plugins/10-plugin.md +++ /dev/null @@ -1,3 +0,0 @@ -# The `qiime2.plugin.Plugin` object - -## TODO: Write dev-docs on this object \ No newline at end of file diff --git a/book/20-understanding/20-interfaces/00-intro.md b/book/20-understanding/20-interfaces/00-intro.md deleted file mode 100644 index 06483cc3..00000000 --- a/book/20-understanding/20-interfaces/00-intro.md +++ /dev/null @@ -1 +0,0 @@ -# Understanding QIIME 2 Interfaces \ No newline at end of file diff --git a/book/20-understanding/20-interfaces/10-plugin-manager.md b/book/20-understanding/20-interfaces/10-plugin-manager.md deleted file mode 100644 index 2199dc66..00000000 --- a/book/20-understanding/20-interfaces/10-plugin-manager.md +++ /dev/null @@ -1,3 +0,0 @@ -# The `qiime2.sdk.PluginManager` object - -## TODO: Write dev-docs on this object \ No newline at end of file diff --git a/book/30-how-to/00-intro.md b/book/30-how-to/00-intro.md deleted file mode 100644 index 6579f832..00000000 --- a/book/30-how-to/00-intro.md +++ /dev/null @@ -1,3 +0,0 @@ -# Introduction - -This section helps you accomplish specific tasks when developing with QIIME 2. \ No newline at end of file diff --git a/book/30-how-to/10-plugins/00-intro.md b/book/30-how-to/10-plugins/00-intro.md deleted file mode 100644 index 4a7e9838..00000000 --- a/book/30-how-to/10-plugins/00-intro.md +++ /dev/null @@ -1 +0,0 @@ -# Accomplishing specific tasks in QIIME 2 Plugins \ No newline at end of file diff --git a/book/30-how-to/10-plugins/10-type-mapping.rst b/book/30-how-to/10-plugins/10-type-mapping.rst deleted file mode 100644 index 0e539a6b..00000000 --- a/book/30-how-to/10-plugins/10-type-mapping.rst +++ /dev/null @@ -1,49 +0,0 @@ -Mapping input semantic types to output semantic types -##################################################### - -We use the ``TypeMatch`` object to map input types to output types. - -.. code-block:: python - - # Beginning of setup - from qiime2.plugin import Plugin, TypeMatch - from qiime2.core.testing.type import IntSequence1, IntSequence2 - from qiime2.core.testing.method import split_ints - from qiime2.plugin import Citations - - citations = Citations.load('citations.bib', package='qiime2.core.testing') - dummy_plugin = Plugin( - name='dummy-plugin', - description='Description of dummy plugin.', - short_description='Dummy plugin for testing.', - version='0.0.0-dev', - website='https://github.com/qiime2/qiime2', - package='qiime2.core.testing', - user_support_text='For help, see https://qiime2.org', - citations=[citations['unger1998does'], citations['berry1997flying']] - ) - # End of setup - - T = TypeMatch([IntSequence1, IntSequence2]) - dummy_plugin.methods.register_function( - function=split_ints, - inputs={ - 'ints': T - }, - parameters={}, - outputs={ - 'left': T, - 'right': T - }, - name='Split sequence of integers in half', - description='This method splits a sequence of integers in half, returning ' - 'the two halves (left and right). If the input sequence\'s ' - 'length is not evenly divisible by 2, the right half will ' - 'have one more element than the left.', - citations=[ - citations['witcombe2006sword'], citations['reimers2012response']] - ) - -Create a ``TypeMatch`` object taking a list of the different types you intend to match. By convention, we name this variable T. - -Use this object as the type of the inputs and outputs you want to match. In the above example, `ints` can take an IntSequence1 or an IntSequence2. `left` and `right` will both be the same type as `ints`. diff --git a/book/30-how-to/20-interfaces/00-intro.md b/book/30-how-to/20-interfaces/00-intro.md deleted file mode 100644 index 7632665d..00000000 --- a/book/30-how-to/20-interfaces/00-intro.md +++ /dev/null @@ -1 +0,0 @@ -# Accomplishing specific tasks in QIIME 2 Interfaces \ No newline at end of file diff --git a/book/30-how-to/20-interfaces/10-accessing-help-text.md b/book/30-how-to/20-interfaces/10-accessing-help-text.md deleted file mode 100644 index eeece4cb..00000000 --- a/book/30-how-to/20-interfaces/10-accessing-help-text.md +++ /dev/null @@ -1 +0,0 @@ -# Accessing help text on plugins, actions, types, and formats \ No newline at end of file diff --git a/book/40-reference/00-intro.md b/book/40-reference/00-intro.md deleted file mode 100644 index ce5b2c5d..00000000 --- a/book/40-reference/00-intro.md +++ /dev/null @@ -1,3 +0,0 @@ -# Introduction - -This portion of the docs will serve as a quick reference for various QIIME 2 terms and APIs. \ No newline at end of file diff --git a/book/40-reference/10-api/00-intro.md b/book/40-reference/10-api/00-intro.md deleted file mode 100644 index 2f1029db..00000000 --- a/book/40-reference/10-api/00-intro.md +++ /dev/null @@ -1,3 +0,0 @@ -# QIIME 2 API reference - -Here you will learn the intended methods of interacting with various parts of the guts of QIIME 2. \ No newline at end of file diff --git a/book/40-reference/10-api/10-usage/00-index.rst b/book/40-reference/10-api/10-usage/00-index.rst deleted file mode 100644 index ce60d8ce..00000000 --- a/book/40-reference/10-api/10-usage/00-index.rst +++ /dev/null @@ -1,4 +0,0 @@ -Usage API -========= - -.. automodule:: qiime2.sdk.usage diff --git a/book/40-reference/10-api/10-usage/10-authors.rst b/book/40-reference/10-api/10-usage/10-authors.rst deleted file mode 100644 index dff5b212..00000000 --- a/book/40-reference/10-api/10-usage/10-authors.rst +++ /dev/null @@ -1,78 +0,0 @@ -Usage API (for example authors) -=============================== -.. contents:: - :local: - -This page outlines elements of the Usage API which are used by example authors -(and overriden by interface drivers) to describe some example situation in the -framework for documentation, testing, or interface generating purposes. - - -.. currentmodule:: qiime2.sdk.usage - -Initializers ------------- -These methods prepare some data for use in an example. - -.. automethod:: Usage.init_artifact -.. automethod:: Usage.init_metadata -.. automethod:: Usage.init_format - -Importing ---------- -These methods demonstrate how to import an artifact. - -.. automethod:: Usage.import_from_format - -Metadata --------- -These methods demonstrate how to manipulate metadata. - -.. automethod:: Usage.get_metadata_column -.. automethod:: Usage.view_as_metadata -.. automethod:: Usage.merge_metadata - -.. _usage-annotations: - -Annotations ------------ -These methods do not return anything, but may be displayed in other ways. - -.. automethod:: Usage.comment -.. automethod:: Usage.help -.. automethod:: Usage.peek - - -Actions -------- -These methods invoke a plugin's action. - -.. automethod:: Usage.action - -Parameter Objects for :meth:`Usage.action` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -These three classes define a deferred action that should be taken by some -interface driver. - -.. autoclass:: UsageAction - :special-members: __init__ - -.. autoclass:: UsageInputs - :special-members: __init__ - -.. autoclass:: UsageOutputNames - :special-members: __init__ - - -.. _results-and-assertions: - -Results and Assertions -~~~~~~~~~~~~~~~~~~~~~~ -The outputs of :meth:`qiime2.sdk.usage.Usage.action` are stored in a vanity -class :class:`qiime2.sdk.usage.UsageOutputs` which contain -:class:`qiime2.sdk.usage.UsageVariable`'s. Assertions are performed on these -output variables. - -.. autoclass:: UsageOutputs -.. autoclass:: UsageVariable - :members: assert_has_line_matching, assert_output_type diff --git a/book/40-reference/10-api/10-usage/20-drivers.rst b/book/40-reference/10-api/10-usage/20-drivers.rst deleted file mode 100644 index 37197d74..00000000 --- a/book/40-reference/10-api/10-usage/20-drivers.rst +++ /dev/null @@ -1,54 +0,0 @@ -Usage API (for interface drivers) -================================= - -.. this unusual mechanism using automethod prevents double indexing the class - while still permitting references to the methods. - -.. autoclass:: qiime2.sdk.usage.Usage - - .. automethod:: __init__ - .. autoattribute:: asynchronous - .. autoattribute:: namespace - .. automethod:: usage_variable - .. automethod:: render - -.. autoclass:: qiime2.sdk.usage.UsageVariable - :noindex: - - .. automethod:: __init__ - .. autoattribute:: name - .. autoattribute:: var_type - .. autoattribute:: value - .. autoattribute:: factory - .. autoattribute:: use - .. autoproperty:: is_deferred - .. automethod:: to_interface_name - .. automethod:: execute - .. automethod:: save - -.. autoclass:: qiime2.sdk.usage.UsageAction - :noindex: - - .. autoattribute:: plugin_id - .. autoattribute:: action_id - .. automethod:: get_action - -.. autoclass:: qiime2.sdk.usage.UsageInputs - :noindex: - - .. automethod:: map_variables - .. automethod:: __getitem__ - .. automethod:: __contains__ - .. automethod:: keys - .. automethod:: values - .. automethod:: items - -.. autoclass:: qiime2.sdk.usage.UsageOutputNames - :noindex: - - .. automethod:: __getitem__ - .. automethod:: __contains__ - .. automethod:: keys - .. automethod:: values - .. automethod:: items - diff --git a/book/40-reference/10-api/10-usage/30-implementations.rst b/book/40-reference/10-api/10-usage/30-implementations.rst deleted file mode 100644 index 2167bb08..00000000 --- a/book/40-reference/10-api/10-usage/30-implementations.rst +++ /dev/null @@ -1,31 +0,0 @@ -Premade Usage Drivers -===================== -.. contents:: - :local: - -These drivers serve as reference implementations and may be convenient for your -own purposes. - -Debug Driver ------------- -.. autoclass:: qiime2.sdk.usage.DiagnosticUsage - - .. automethod:: __init__ - .. automethod:: render - -.. autoclass:: qiime2.sdk.usage.DiagnosticUsage.DiagnosticUsageRecord - -Execution Driver ----------------- -.. autoclass:: qiime2.sdk.usage.ExecutionUsage - :members: render - :special-members: __init__ - -.. autoclass:: qiime2.sdk.usage.ExecutionUsageVariable - -Artifact API Driver -------------------- -.. autoclass:: qiime2.plugins.ArtifactAPIUsage - :members: render - :special-members: __init__ -.. autoclass:: qiime2.plugins.ArtifactAPIUsageVariable diff --git a/book/40-reference/10-api/20-cache/00-index.rst b/book/40-reference/10-api/20-cache/00-index.rst deleted file mode 100644 index 4709cd0e..00000000 --- a/book/40-reference/10-api/20-cache/00-index.rst +++ /dev/null @@ -1,4 +0,0 @@ -Artifact Cache -============== - -.. automodule:: qiime2.core.cache \ No newline at end of file diff --git a/book/40-reference/10-api/20-cache/10-cache.rst b/book/40-reference/10-api/20-cache/10-cache.rst deleted file mode 100644 index 7d6af7e4..00000000 --- a/book/40-reference/10-api/20-cache/10-cache.rst +++ /dev/null @@ -1,23 +0,0 @@ -Cache -===== - -.. automethod:: qiime2.core.cache.get_cache - -The Cache Class ---------------- - -.. autoclass:: qiime2.core.cache.Cache - - .. automethod:: __init__ - .. automethod:: __enter__ - .. automethod:: __exit__ - .. automethod:: is_cache - .. automethod:: create_pool - .. automethod:: garbage_collection - .. automethod:: save - .. automethod:: load - .. automethod:: remove - .. automethod:: get_data - .. automethod:: get_keys - .. automethod:: get_pools - .. automethod:: get_processes \ No newline at end of file diff --git a/book/40-reference/10-api/20-cache/20-pool.rst b/book/40-reference/10-api/20-cache/20-pool.rst deleted file mode 100644 index 3b8ad734..00000000 --- a/book/40-reference/10-api/20-cache/20-pool.rst +++ /dev/null @@ -1,12 +0,0 @@ -Pool -==== - -.. autoclass:: qiime2.core.cache.Pool - - .. automethod:: __init__ - .. automethod:: __enter__ - .. automethod:: __exit__ - .. automethod:: save - .. automethod:: load - .. automethod:: remove - .. automethod:: get_data \ No newline at end of file diff --git a/book/40-reference/90-glossary.rst b/book/40-reference/90-glossary.rst deleted file mode 100644 index ad11089b..00000000 --- a/book/40-reference/90-glossary.rst +++ /dev/null @@ -1,135 +0,0 @@ -Glossary -======== -This page serves as a reference for other documents, we don't recommend reading -it without the accompanying context provided by the rest of this documentation. - -.. glossary:: - Action - A generic term to describe a concrete :term:`method`, :term:`visualizer`, - or :term:`pipeline`. Actions accept parameters and/or files - (:term:`artifacts ` or :term:`metadata`) as input, and generate - some kind of output. - - Archive - The directory structure of a QIIME 2 :term:`Result`. Contains *at least* - a root directory (named by :term:`UUID`) and a ``VERSION`` file within - that directory. - - Artifact - A QIIME 2 :term:`Result` that contains data to operate on. - - Deployment - An installation of QIIME 2 as well as zero-or-more :term:`interfaces - ` and :term:`plugins `. - - Directory Format - A string that represents a particular layout of files and or directories - as well as how their contents will be structured. - - Format - A string that represents a particular file format. - - Framework - The engine of orchestration that enables QIIME 2 to function together as a - cohesive unit. - - Identifier - A unique value that denotes an individual sample or feature. - - Identity - Distinguishes a piece of data. QIIME 2 does not consider a rename (like - UNIX ``mv``) to change identity, however re-running a command, would - change identity. - - Input - Data provided to an :term:`action`. Can be an :term:`artifact` or - :term:`metadata`. - - Interface - A user-interface responsible for coordinating user-specified intent into - :term:`framework`-driven action. - - Metadata - Columnar data for annotating additional values to existing data. Operates - along Sample IDs or Feature IDs. - - Method - A method accepts some combination of QIIME 2 :term:`artifacts ` - and :term:`parameters ` as :term:`input`, and produces one or - more QIIME 2 artifacts as :term:`output`. - - Output - Objects returned by an :term:`action`. Can be :term:`artifact(s) - ` or :term:`visualization(s) `. - - Parameter - A value that alters the behavior of an :term:`action`. - - Payload - Data that is meant for primary consumption or interpretation (in contrast - to *metadata* which may be useful retrospectively, but is not primarily - useful). - - Pipeline - A pipeline accepts some combination of QIIME 2 :term:`artifacts - ` and :term:`parameters ` as :term:`input`, and - produces one or more QIIME 2 :term:`artifacts ` and/or - :term:`visualizations ` as :term:`output`. - - Plugin - A discrete module that registers some form of additional functionality - with the :term:`framework`, including new :term:`methods `, - :term:`visualizers `, :term:`formats `, or - :term:`transformers `. - - Primitive Type - A :term:`type` that is used to communicate parameters to an - :term:`interface`. These are predefined by the :term:`framework` and - cannot be extended. - - Result - A generic term for either a :term:`Visualization` or an :term:`Artifact`. - - Provenance - Data describing how an analysis was performed, - captured automatically whenever users perform a QIIME 2 :term:`Action`. - Provenance information describes the host system, the computing environment, - Actions performed, parameters passed, primary sources cited, and more. - - Semantic Type - A :term:`type` that is used to classify :term:`artifacts` and - how they can be used. These types may be extended by - :term:`plugins`. - - Transformer - A function registered on the :term:`framework` capable of converting data - in one :term:`format` into data of another :term:`format`. - - Type - A name that is used to classify how a piece of data may be used. Most - commonly used to refer to :term:`Semantic Type`, but can also refer to - :term:`Primitive Type` and :term:`Visualization (Type)`. - - UUID - Universally Unique IDentifier, in the context of QIIME 2, almost certainly - refers to a *Version 4* UUID, which is a randomly generated ID. See this - `RFC `_ or this `wikipedia entry - `_ for - details. - - View - A particular representation of data. This includes on-disk formats and - in-memory data structures (objects). - - Visualization - A QIIME 2 :term:`Result` that contains an interactive visualization. - - Visualization (Type) - The :term:`type` of a :term:`visualization`. There are no subtyping - relations between this type and any other (it is a singleton) and cannot - be extended (because it is a singleton). - - Visualizer - A visualizer accepts some combination of QIIME 2 :term:`artifacts - ` and :term:`parameters ` as :term:`input`, and - produces exactly one :term:`visualization` as :term:`output`. diff --git a/book/_config.yml b/book/_config.yml index cdd33bb9..efeac22c 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -1,18 +1,23 @@ title: Developing with QIIME 2 author: QIIME 2 Project -logo: assets/q2dev.svg copyright: "2023" exclude_patterns: [_build, Thumbs.db, .DS_Store, "**.ipynb_checkpoints"] sphinx: extra_extensions: - sphinx.ext.autodoc + - sphinx.ext.napoleon - sphinx.ext.doctest - sphinx.ext.intersphinx - sphinx.ext.coverage - sphinx.ext.mathjax - sphinx.ext.githubpages - sphinxcontrib.bibtex + config: + html_theme_options: + logo: + image_light: _static/q2dev.svg + image_dark: _static/q2dev_darkmode.svg execute: execute_notebooks: force @@ -22,7 +27,7 @@ latex: targetname: book.tex bibtex_bibfiles: - - assets/references.bib + - _static/references.bib repository: url: https://github.com/caporaso-lab/developing-with-qiime2 @@ -32,6 +37,4 @@ repository: html: use_issues_button: true use_repository_button: true - favicon: assets/favicon.ico - comments: - hypothesis: true + favicon: _static/favicon.ico diff --git a/book/_static/custom.css b/book/_static/custom.css new file mode 100644 index 00000000..16803a9b --- /dev/null +++ b/book/_static/custom.css @@ -0,0 +1,54 @@ +#rtd-footer-container { + margin-top: 0px !important; +} + +.navbar-nav li { + line-height: 1.4; + margin-top: 0.2rem; +} + +.bd-sidebar-primary .sidebar-primary-items__end { + margin-bottom: 0px !important; +} + +/* I don't know why jupyter book did this + The natural pydata theme has a good default already. +*/ +.bd-main { + flex-grow: 1; +} + +/* probably they noticed the weird center, but this is how you fix that: */ +.bd-main .bd-content { + justify-content: flex-start; +} + +/* put prev-next navigation at the bottom of the page */ +.prev-next-footer { + /* the parent is a flexbox with a known size, so this work correctly */ + margin-top: auto; + margin-bottom: 0.5rem; +} + +/* Don't word-wrap internal references */ +article a.internal { + white-space: nowrap; +} + +/* Fix the intra-page toc icon */ +.bd-sidebar-secondary .onthispage svg.fa-list { + margin-right: 1ch; +} + +/* let's only have a single max-width please */ +.bd-main .bd-content .bd-article-container { + max-width: unset !important; +} + +html { + --pst-sidebar-font-size: 1rem; +} + +dl.py { + margin-bottom: 3rem; +} \ No newline at end of file diff --git a/book/assets/favicon.ico b/book/_static/favicon.ico similarity index 100% rename from book/assets/favicon.ico rename to book/_static/favicon.ico diff --git a/book/assets/q2dev.svg b/book/_static/q2dev.svg similarity index 97% rename from book/assets/q2dev.svg rename to book/_static/q2dev.svg index 6c6ebac0..af621dc4 100644 --- a/book/assets/q2dev.svg +++ b/book/_static/q2dev.svg @@ -51,7 +51,7 @@ - + dev diff --git a/book/_static/q2dev_darkmode.svg b/book/_static/q2dev_darkmode.svg new file mode 100644 index 00000000..a6489675 --- /dev/null +++ b/book/_static/q2dev_darkmode.svg @@ -0,0 +1,58 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + dev + + + diff --git a/book/assets/references.bib b/book/_static/references.bib similarity index 96% rename from book/assets/references.bib rename to book/_static/references.bib index 80c03d4b..3fd881bf 100644 --- a/book/assets/references.bib +++ b/book/_static/references.bib @@ -48,3 +48,10 @@ @ARTICLE{qiime2-2019 year = 2019, language = "en" } + + +@MISC{diataxis, + author = {Procida, Daniele}, + title = {{Diátaxis documentation framework}}, + url = {https://diataxis.fr/} +} \ No newline at end of file diff --git a/book/_toc.yml b/book/_toc.yml index 9c93b371..4b56ae0e 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -2,51 +2,53 @@ # Learn more at https://jupyterbook.org/customize/toc.html format: jb-book -root: 00-intro +root: intro parts: - - caption: "Tutorials" + + - caption: "Docs" chapters: - - file: 10-tutorial/00-intro - - file: 10-tutorial/10-plugins/00-intro - sections: - - file: 10-tutorial/10-plugins/10-plugin-setup - - file: 10-tutorial/10-plugins/20-registering-actions - - file: 10-tutorial/20-interfaces/00-intro - sections: - - file: 10-tutorial/20-interfaces/10-plugin-manager - - caption: "Understanding QIIME 2" + - file: docs/intro + title: Introduction + + - caption: "Plugins" chapters: - - file: 20-understanding/00-intro - - file: 20-understanding/10-plugins/00-intro + - file: plugins/intro + title: Introduction + - file: plugins/tutorials/intro sections: - - file: 20-understanding/10-plugins/10-plugin - - file: 20-understanding/20-interfaces/00-intro + - file: plugins/tutorials/developing-code + - file: plugins/tutorials/create/intro + options: + numbered: true + sections: + - file: plugins/tutorials/create/getting-started + - file: plugins/tutorials/create/package + - file: plugins/tutorials/create/plugin + - file: plugins/how-to-guides/intro sections: - - file: 20-understanding/20-interfaces/10-plugin-manager - - caption: "How-to guides" + - file: plugins/how-to-guides/add-citation + - file: plugins/how-to-guides/usage-example + - file: plugins/how-to-guides/type-map + - file: plugins/how-to-guides/add-ci + - file: plugins/explainers/intro + - file: plugins/references/intro + title: "References" + + - caption: "Interfaces" chapters: - - file: 30-how-to/00-intro - - file: 30-how-to/10-plugins/00-intro - sections: - - file: 30-how-to/10-plugins/10-type-mapping - - file: 30-how-to/20-interfaces/00-intro - sections: - - file: 30-how-to/20-interfaces/10-accessing-help-text - - caption: "Reference" + - file: interfaces/intro + title: Introduction + + - caption: "Framework Internals" chapters: - - file: 40-reference/00-intro - - file: 40-reference/10-api/00-intro - sections: - - file: 40-reference/10-api/10-usage/00-index - sections: - - file: 40-reference/10-api/10-usage/10-authors - - file: 40-reference/10-api/10-usage/20-drivers - - file: 40-reference/10-api/10-usage/30-implementations - - file: 40-reference/10-api/20-cache/00-index - sections: - - file: 40-reference/10-api/20-cache/10-cache - - file: 40-reference/10-api/20-cache/20-pool - - file: 40-reference/90-glossary - - caption: "Back matter" + - file: framework/intro + title: Introduction + + - caption: "CI Internals" + chapters: + - file: ci/intro + title: Introduction + + - caption: "Back Matter" chapters: - - file: 99-bibliography + - file: bibliography diff --git a/book/99-bibliography.md b/book/bibliography.md similarity index 100% rename from book/99-bibliography.md rename to book/bibliography.md diff --git a/book/ci/intro.md b/book/ci/intro.md new file mode 100644 index 00000000..88f0239b --- /dev/null +++ b/book/ci/intro.md @@ -0,0 +1 @@ +# Introduction to CI and Release Process \ No newline at end of file diff --git a/book/docs/intro.md b/book/docs/intro.md new file mode 100644 index 00000000..f81fb1dd --- /dev/null +++ b/book/docs/intro.md @@ -0,0 +1 @@ +# Introduction to Documentation \ No newline at end of file diff --git a/book/framework/intro.md b/book/framework/intro.md new file mode 100644 index 00000000..8feaa25a --- /dev/null +++ b/book/framework/intro.md @@ -0,0 +1 @@ +# Introduction to the Framework \ No newline at end of file diff --git a/book/interfaces/intro.md b/book/interfaces/intro.md new file mode 100644 index 00000000..932e92e9 --- /dev/null +++ b/book/interfaces/intro.md @@ -0,0 +1 @@ +# Introduction to Writing Interfaces \ No newline at end of file diff --git a/book/intro.md b/book/intro.md new file mode 100644 index 00000000..b4180e2d --- /dev/null +++ b/book/intro.md @@ -0,0 +1,39 @@ +# Developing with QIIME 2 + +👋 Welcome to our book on QIIME 2 {cite}`qiime2-2019` development! +*Developing with QIIME 2* is designed to help you write plugins, interfaces, and contribute to the QIIME 2 framework. + +## About +The content in this book is organized under the [Diátaxis](https://diataxis.fr/) framework {cite}`diataxis`. +This means that you can expect Tutorials, How-To-Guides, Explainers, and References which each serve a different goal for the reader. + +```{list-table} +:header-rows: 1 + +* - Type + - Purpose + +* - Tutorial + - Guided exploration of a topic + +* - How To Guide + - Specific instructions to complete a single task + +* - Explainer + - Explanation on the *why* behind some topic + +* - Reference + - A detailed specification of an entity or task +``` + +## Table of Contents +This book is split into multiple parts. +Each part covers a complete topic in the QIIME 2 ecosystem. +You do not need to master all of these sections to develop with QIIME 2. +For example, if you are interested in creating plugins, +then the only section you need to concern yourself with is the **Plugins** section. +Other topics, such as **Framework Internals** and **CI Internals**, +are advanced topics that are mostly useful for the QIIME 2 Development Team itself. + +```{tableofcontents} +``` diff --git a/book/plugins/explainers/intro.md b/book/plugins/explainers/intro.md new file mode 100644 index 00000000..e98cd7ea --- /dev/null +++ b/book/plugins/explainers/intro.md @@ -0,0 +1 @@ +# Explainers diff --git a/book/plugins/how-to-guides/add-ci.md b/book/plugins/how-to-guides/add-ci.md new file mode 100644 index 00000000..5ed55d9e --- /dev/null +++ b/book/plugins/how-to-guides/add-ci.md @@ -0,0 +1 @@ +# Adding Continuous Integration Tests \ No newline at end of file diff --git a/book/plugins/how-to-guides/add-citation.md b/book/plugins/how-to-guides/add-citation.md new file mode 100644 index 00000000..32fd4ba8 --- /dev/null +++ b/book/plugins/how-to-guides/add-citation.md @@ -0,0 +1 @@ +# Adding Citations to your Plugin \ No newline at end of file diff --git a/book/plugins/how-to-guides/intro.md b/book/plugins/how-to-guides/intro.md new file mode 100644 index 00000000..a8fc5fd5 --- /dev/null +++ b/book/plugins/how-to-guides/intro.md @@ -0,0 +1,4 @@ +# How To Guides + +```{tableofcontents} +``` \ No newline at end of file diff --git a/book/plugins/how-to-guides/type-map.md b/book/plugins/how-to-guides/type-map.md new file mode 100644 index 00000000..fafc3e0a --- /dev/null +++ b/book/plugins/how-to-guides/type-map.md @@ -0,0 +1 @@ +# Dynamic Output Types and Constraints \ No newline at end of file diff --git a/book/plugins/how-to-guides/usage-example.md b/book/plugins/how-to-guides/usage-example.md new file mode 100644 index 00000000..bbb70499 --- /dev/null +++ b/book/plugins/how-to-guides/usage-example.md @@ -0,0 +1 @@ +# Writing Usage Examples \ No newline at end of file diff --git a/book/plugins/intro.md b/book/plugins/intro.md new file mode 100644 index 00000000..21340ad0 --- /dev/null +++ b/book/plugins/intro.md @@ -0,0 +1,2 @@ +# Introduction to Writing Plugins + diff --git a/book/plugins/references/intro.md b/book/plugins/references/intro.md new file mode 100644 index 00000000..5674d3da --- /dev/null +++ b/book/plugins/references/intro.md @@ -0,0 +1,4 @@ +# Plugin References + +## Usage API +Plugins only use one half of the Usage API which is described in [this API reference](https://dev.qiime2.org/latest/api-reference/usage/authors/). \ No newline at end of file diff --git a/book/plugins/tutorials/create/getting-started.md b/book/plugins/tutorials/create/getting-started.md new file mode 100644 index 00000000..a34b7d56 --- /dev/null +++ b/book/plugins/tutorials/create/getting-started.md @@ -0,0 +1,12 @@ +# Getting Started + +:::{note} +This tutorial will follow the development of a QIIME 2 plugin from start to finish. +We will assume you have a development environment which includes: +a source code editor, +a command line terminal, +and a directory browser or file-tree. +If you do not have an existing environment +(or if you have only worked inside of notebooks), +then please read [](../developing-code.md) first. +::: \ No newline at end of file diff --git a/book/plugins/tutorials/create/intro.md b/book/plugins/tutorials/create/intro.md new file mode 100644 index 00000000..50069e18 --- /dev/null +++ b/book/plugins/tutorials/create/intro.md @@ -0,0 +1,5 @@ +# Creating a Plugin + + +```{tableofcontents} +``` \ No newline at end of file diff --git a/book/plugins/tutorials/create/package.md b/book/plugins/tutorials/create/package.md new file mode 100644 index 00000000..4083f265 --- /dev/null +++ b/book/plugins/tutorials/create/package.md @@ -0,0 +1 @@ +# Python Package \ No newline at end of file diff --git a/book/plugins/tutorials/create/plugin.md b/book/plugins/tutorials/create/plugin.md new file mode 100644 index 00000000..cb3af007 --- /dev/null +++ b/book/plugins/tutorials/create/plugin.md @@ -0,0 +1 @@ +# Plugin Setup \ No newline at end of file diff --git a/book/plugins/tutorials/developing-code.md b/book/plugins/tutorials/developing-code.md new file mode 100644 index 00000000..e5df59fe --- /dev/null +++ b/book/plugins/tutorials/developing-code.md @@ -0,0 +1 @@ +# Developing Code \ No newline at end of file diff --git a/book/plugins/tutorials/intro.md b/book/plugins/tutorials/intro.md new file mode 100644 index 00000000..678ccd7c --- /dev/null +++ b/book/plugins/tutorials/intro.md @@ -0,0 +1,5 @@ +# Tutorials + + +```{tableofcontents} +``` \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 7e821e45..47a56abb 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1 @@ -jupyter-book -matplotlib -numpy +jupyter-book \ No newline at end of file