diff --git a/book/_static/custom.css b/book/_static/custom.css index 16d2b0e..8c0f739 100644 --- a/book/_static/custom.css +++ b/book/_static/custom.css @@ -55,6 +55,13 @@ html[data-theme="light"] { } -dl.py { +dl[class]:not(.option-list, .field-list, .footnote, .glossary, .simple) { margin-bottom: 3rem; +} + +dl[class]:not(.option-list, .field-list, .footnote, .glossary, .simple) > dd { + border-left: 1px solid var(--pst-color-border);; + padding-left: 1.7rem; + margin-left: 0.25rem; + margin-bottom: 3rem; } \ No newline at end of file diff --git a/book/_toc.yml b/book/_toc.yml index cc58743..05a026c 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -46,7 +46,16 @@ parts: - file: plugins/references/intro sections: - file: plugins/references/antipatterns - - file: plugins/references/api + - file: plugins/references/api/intro + sections: + - file: plugins/references/api/plugin + - file: plugins/references/api/formats + - file: plugins/references/api/types + - file: plugins/references/api/citations + - file: plugins/references/api/testing + - file: plugins/references/api/utils + - file: plugins/references/api/context + - file: plugins/references/api/usage - file: plugins/references/metadata-api - caption: "Interfaces 🧩" diff --git a/book/docs/developer-documentation.md b/book/docs/developer-documentation.md index fb35737..f734e47 100644 --- a/book/docs/developer-documentation.md +++ b/book/docs/developer-documentation.md @@ -7,3 +7,9 @@ Contributions from others are welcomed and acknowledged via the project's [GitHu At the moment, while we're still laying the groundwork, we're accepting only [specific contributions](https://github.com/caporaso-lab/developing-with-qiime2/labels/help%20wanted). If you have suggestions or feedback [we'd love to hear from you](https://github.com/caporaso-lab/developing-with-qiime2/issues). + + +## Finding docstring sources + +For API documentation, the source of documentation for code entities will be defined by their respective docstrings. +In many cases, the linkcode extension will provide a link (via ``[source]``) to the source code of these entities. However in certain cases, (such as plugin types), autodoc can only find docstrings at the provided module path (and linkcode is unable to resolve a source). This means that these docstrings will be found in ``qiime2/plugin/__init__.py`` (or wherever the module provided to autodoc indicates). \ No newline at end of file diff --git a/book/interfaces/references/api.md b/book/interfaces/references/api.md index 63a1703..5d1f190 100644 --- a/book/interfaces/references/api.md +++ b/book/interfaces/references/api.md @@ -28,7 +28,6 @@ When developing a QIIME 2 interface, you will use APIs defined in the `qiime2.sd .. autofunction:: qiime2.sdk.Method .. autofunction:: qiime2.sdk.Visualizer .. autofunction:: qiime2.sdk.Pipeline -.. autofunction:: qiime2.sdk.Context ``` ### Utility functions @@ -39,11 +38,6 @@ When developing a QIIME 2 interface, you will use APIs defined in the `qiime2.sd .. autofunction:: qiime2.sdk.type_from_ast ``` -### Citations - -```{eval-rst} -.. autofunction:: qiime2.sdk.Citations -``` ### Exceptions diff --git a/book/plugins/references/api.md b/book/plugins/references/api.md deleted file mode 100644 index ddd38b0..0000000 --- a/book/plugins/references/api.md +++ /dev/null @@ -1,82 +0,0 @@ -(plugin-developer-api)= -# Plugin developer API - -When developing a QIIME 2 plugin, you will use APIs defined in the `qiime2.plugin` submodule. - -## Plugin development API - -(Plugin-api-docs)= -### The `Plugin` object -```{eval-rst} -.. autofunction:: qiime2.plugin.Plugin -``` - -### Formats -```{eval-rst} -.. autofunction:: qiime2.plugin.TextFileFormat -.. autofunction:: qiime2.plugin.BinaryFileFormat -.. autofunction:: qiime2.plugin.DirectoryFormat -``` - -### `Action` input and output - -#### Sematic types -```{eval-rst} -.. autofunction:: qiime2.plugin.SemanticType -.. autofunction:: qiime2.plugin.Properties -``` - -#### Primitives and modifiers -```{eval-rst} -.. autofunction:: qiime2.plugin.Visualization -.. autofunction:: qiime2.plugin.Set -.. autofunction:: qiime2.plugin.List -.. autofunction:: qiime2.plugin.Collection -.. autofunction:: qiime2.plugin.Bool -.. autofunction:: qiime2.plugin.Int -.. autofunction:: qiime2.plugin.Float -.. autofunction:: qiime2.plugin.Range -.. autofunction:: qiime2.plugin.Start -.. autofunction:: qiime2.plugin.End -.. autofunction:: qiime2.plugin.Str -.. autofunction:: qiime2.plugin.Choices -.. autofunction:: qiime2.plugin.Jobs -.. autofunction:: qiime2.plugin.Threads -``` - -#### Metadata -```{eval-rst} -.. autofunction:: qiime2.plugin.Metadata -.. autofunction:: qiime2.plugin.MetadataColumn -.. autofunction:: qiime2.plugin.Categorical -.. autofunction:: qiime2.plugin.Numeric -``` - -#### Support functions -```{eval-rst} -.. autofunction:: qiime2.plugin.TypeMap -.. autofunction:: qiime2.plugin.TypeMatch -``` - -### Citations -```{eval-rst} -.. autofunction:: qiime2.plugin.Citations -.. autofunction:: qiime2.plugin.CitationRecord -``` - -### Utility functions -```{eval-rst} -.. autofunction:: qiime2.plugin.get_available_cores -``` - -### Exceptions -```{eval-rst} -.. autofunction:: qiime2.plugin.ValidationError -``` - -## Plugin testing API - -```{eval-rst} -.. automodule:: qiime2.plugin.testing - :members: -``` \ No newline at end of file diff --git a/book/plugins/references/api/citations.md b/book/plugins/references/api/citations.md new file mode 100644 index 0000000..a63ab77 --- /dev/null +++ b/book/plugins/references/api/citations.md @@ -0,0 +1,14 @@ +(Citations-api-docs)= +# Citations +QIIME 2 can automatically track citations as a user performs an analysis. +This is done via and lists of them +( and ). + + +```{eval-rst} +.. autoclass:: qiime2.plugin.Citations + :members: + :special-members: __iter__ + +.. autoclass:: qiime2.plugin.CitationRecord +``` \ No newline at end of file diff --git a/book/plugins/references/api/context.md b/book/plugins/references/api/context.md new file mode 100644 index 0000000..0882d67 --- /dev/null +++ b/book/plugins/references/api/context.md @@ -0,0 +1,10 @@ +# Pipeline Context Object +The context object is available to pipelines as a required first argument ``ctx``. +Plugins may use these methods to invoke other registered actions or create artifacts. + + +```{eval-rst} +.. automethod:: qiime2.sdk.Context.get_action +.. automethod:: qiime2.sdk.Context.make_artifact + +``` \ No newline at end of file diff --git a/book/plugins/references/api/formats.md b/book/plugins/references/api/formats.md new file mode 100644 index 0000000..3256a2f --- /dev/null +++ b/book/plugins/references/api/formats.md @@ -0,0 +1,10 @@ +(Formats-api-docs)= +# Formats + +```{eval-rst} +.. autoclass:: qiime2.plugin.TextFileFormat +.. autoclass:: qiime2.plugin.BinaryFileFormat +.. autoclass:: qiime2.plugin.DirectoryFormat +.. autofunction:: qiime2.plugin.SingleFileDirectoryFormat +.. autoclass:: qiime2.plugin.ValidationError +``` \ No newline at end of file diff --git a/book/plugins/references/api/intro.md b/book/plugins/references/api/intro.md new file mode 100644 index 0000000..41edbb6 --- /dev/null +++ b/book/plugins/references/api/intro.md @@ -0,0 +1,150 @@ +(plugin-developer-api)= +# Plugin Development API +This section details the public API for plugin development. +Broadly speaking, everything that is necessary to build a QIIME 2 plugin is +available in `qiime2.plugin` or `qiime2.metadata`. + +## Individual Topics +```{tableofcontents} +``` + +## Plugin API List + +```{eval-rst} +.. rubric:: Plugin Object +.. autosummary:: + :nosignatures: + + qiime2.plugin.Plugin + +.. rubric:: Registration +.. currentmodule:: qiime2.plugin +.. autosummary:: + :nosignatures: + + plugin.PluginMethods.register_function + plugin.PluginVisualizers.register_function + plugin.PluginPipelines.register_function + Plugin.register_validator + Plugin.register_transformer + Plugin.register_formats + Plugin.register_views + Plugin.register_semantic_types + Plugin.register_semantic_type_to_format + Plugin.register_artifact_class + +.. currentmodule:: None +.. rubric:: Formats +.. autosummary:: + :nosignatures: + + qiime2.plugin.TextFileFormat + qiime2.plugin.BinaryFileFormat + qiime2.plugin.DirectoryFormat + qiime2.plugin.SingleFileDirectoryFormat + + qiime2.plugin.ValidationError + +.. rubric:: Types +.. autosummary:: + :nosignatures: + + qiime2.plugin.SemanticType + qiime2.plugin.Properties + qiime2.plugin.Visualization + qiime2.plugin.Bool + qiime2.plugin.Str + qiime2.plugin.Int + qiime2.plugin.Float + qiime2.plugin.Threads + qiime2.plugin.Jobs + qiime2.plugin.Choices + qiime2.plugin.Range + qiime2.plugin.Start + qiime2.plugin.End + qiime2.plugin.Metadata + qiime2.plugin.MetadataColumn + qiime2.plugin.Categorical + qiime2.plugin.Numeric + qiime2.plugin.Set + qiime2.plugin.List + qiime2.plugin.Collection + qiime2.plugin.TypeMap + qiime2.plugin.TypeMatch + +.. rubric:: Citations +.. autosummary:: + :nosignatures: + + qiime2.plugin.Citations + qiime2.plugin.CitationRecord + +.. rubric:: Testing +.. autosummary:: + :nosignatures: + + qiime2.plugin.testing.TestPluginBase + qiime2.plugin.testing.assert_no_nans_in_tables + +.. rubric:: Utilities +.. autosummary:: + :nosignatures: + + qiime2.util.duplicate + qiime2.util.redirected_stdio + qiime2.plugin.util.transform + qiime2.plugin.util.get_available_cores +``` + +## Additional Objects +These objects are not part of the `qiime2.plugin` module, but are commonly used +by plugins (and users). + +```{eval-rst} +.. rubric:: Metadata +.. autosummary:: + :nosignatures: + + qiime2.Metadata + qiime2.MetadataColumn + qiime2.NumericMetadataColumn + qiime2.CategoricalMetadataColumn + +.. rubric:: Pipeline Context Object (ctx) +.. currentmodule:: qiime2.sdk +.. autosummary:: + + Context.get_action + Context.make_artifact + +.. currentmodule:: qiime2.sdk.usage +.. rubric:: Usage Examples +.. autosummary:: + :nosignatures: + + Usage.init_artifact + Usage.init_artifact_from_url + Usage.init_artifact_collection + Usage.init_metadata + Usage.init_metadata_from_url + Usage.init_format + Usage.import_from_format + Usage.construct_artifact_collection + Usage.get_artifact_collection_member + Usage.get_metadata_column + Usage.view_as_metadata + Usage.merge_metadata + Usage.comment + Usage.help + Usage.peek + Usage.action + Usage.UsageAction + Usage.UsageInputs + Usage.UsageOutputNames + UsageOutputs + UsageVariable + UsageVariable.assert_has_line_matching + UsageVariable.assert_output_type + +.. currentmodule:: None +``` diff --git a/book/plugins/references/api/plugin.md b/book/plugins/references/api/plugin.md new file mode 100644 index 0000000..87dd80a --- /dev/null +++ b/book/plugins/references/api/plugin.md @@ -0,0 +1,23 @@ +(Plugin-api-docs)= +# Plugin & Registration +```{eval-rst} +.. autoclass:: qiime2.plugin.Plugin + :members: + +``` + +## Action registration +The following classes exist only on an instantiated object and are generally accessed via +``plugin.methods``, ``plugin.visualizers``, and ``plugin.pipelines``. At this time, ``register_function`` is the only +interesting method for a plugin developer. Otherwise these objects are essentially dictionaries to makes generating interfaces convenient. + +```{eval-rst} +.. autoclass:: qiime2.plugin.plugin.PluginMethods + :members: register_function + +.. autoclass:: qiime2.plugin.plugin.PluginVisualizers + :members: register_function + +.. autoclass:: qiime2.plugin.plugin.PluginPipelines + :members: register_function +``` \ No newline at end of file diff --git a/book/plugins/references/api/testing.md b/book/plugins/references/api/testing.md new file mode 100644 index 0000000..62acbe7 --- /dev/null +++ b/book/plugins/references/api/testing.md @@ -0,0 +1,11 @@ +(Testing-api-docs)= +# Testing + +```{eval-rst} + +.. autoclass:: qiime2.plugin.testing.TestPluginBase + :members: + +.. autofunction:: qiime2.plugin.testing.assert_no_nans_in_tables + +``` \ No newline at end of file diff --git a/book/plugins/references/api/types.md b/book/plugins/references/api/types.md new file mode 100644 index 0000000..0013779 --- /dev/null +++ b/book/plugins/references/api/types.md @@ -0,0 +1,98 @@ +(Types-api-docs)= +# Types + + +## Semantic Type +```{eval-rst} +.. autofunction:: qiime2.plugin.SemanticType + +``` +### Predicates +```{eval-rst} +.. Note to developers, the signature has to be overridden manually as autodoc + picks up __new__ on the template which exists to handle pickling but has an + uninformative signature. +.. autoclass:: qiime2.plugin.Properties(*include, exclude=()) +``` + +## Visualization type +```{eval-rst} +.. autodata:: qiime2.plugin.Visualization + :annotation: +``` + +## Primitive types +These are types that all QIIME 2 interfaces will recognize and generate +user affordances for. + +### Basic types +```{eval-rst} + +.. autodata:: qiime2.plugin.Bool + :annotation: + +.. autodata:: qiime2.plugin.Str + :annotation: + +.. autodata:: qiime2.plugin.Int + :annotation: + +.. autodata:: qiime2.plugin.Float + :annotation: + +.. autodata:: qiime2.plugin.Threads + :annotation: + +.. autodata:: qiime2.plugin.Jobs + :annotation: +``` + +### Predicates +```{eval-rst} +.. Note to developers, the signature has to be overridden manually as autodoc + picks up __new__ on the template which exists to handle pickling but has an + uninformative signature. +.. autoclass:: qiime2.plugin.Choices(*choices) + +.. Note to developers, the signature has to be overridden manually as autodoc + picks up __new__ on the template which exists to handle pickling but has an + uninformative signature. +.. autoclass:: qiime2.plugin.Range([start], end, inclusive_start=True, inclusive_end=False) + +.. autofunction:: qiime2.plugin.Start +.. autofunction:: qiime2.plugin.End +``` + +### Metadata +These primitive types represent tabular metadata, where unique identifiers can +be associated with columns. Typically these are used to represent per-sample or +per-feature metadata. But there is nothing special about those axes. + +```{eval-rst} +.. autodata:: qiime2.plugin.Metadata + :annotation: + +.. autodata:: qiime2.plugin.MetadataColumn + :annotation: = MetadataColumn[Categorical | Numeric] + +.. autodata:: qiime2.plugin.Categorical + :annotation: + +.. autodata:: qiime2.plugin.Numeric + :annotation: +``` + +## Collections +Collections may be used with `Semantic`, `Visualization`, and basic `Primitive` types. +```{eval-rst} +.. autodata:: qiime2.plugin.Set +.. autodata:: qiime2.plugin.List +.. autodata:: qiime2.plugin.Collection +``` + +## Dependent Types + +```{eval-rst} +.. autoclass:: qiime2.plugin.TypeMap +.. autoclass:: qiime2.plugin.TypeMatch +``` \ No newline at end of file diff --git a/book/plugins/references/api/usage.md b/book/plugins/references/api/usage.md new file mode 100644 index 0000000..99fdfbe --- /dev/null +++ b/book/plugins/references/api/usage.md @@ -0,0 +1,88 @@ +# Usage Examples + +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. + +```{eval-rst} +.. currentmodule:: qiime2.sdk.usage +``` + +## Initializers +These methods prepare some data for use in an example. + +```{eval-rst} +.. automethod:: Usage.init_artifact +.. automethod:: Usage.init_artifact_from_url +.. automethod:: Usage.init_artifact_collection +.. automethod:: Usage.init_metadata +.. automethod:: Usage.init_metadata_from_url +.. automethod:: Usage.init_format +``` + +## Importing +These methods demonstrate how to import an artifact. + +```{eval-rst} +.. automethod:: Usage.import_from_format +``` + +## Collections +These methods demonstrate how to manipulate collections. +```{eval-rst} +.. automethod:: Usage.construct_artifact_collection +.. automethod:: Usage.get_artifact_collection_member +``` + +## Metadata +These methods demonstrate how to manipulate metadata. + +```{eval-rst} +.. automethod:: Usage.get_metadata_column +.. automethod:: Usage.view_as_metadata +.. automethod:: Usage.merge_metadata +``` + +## Annotations +These methods do not return anything, but may be displayed in other ways. + +```{eval-rst} +.. automethod:: Usage.comment +.. automethod:: Usage.help +.. automethod:: Usage.peek +``` + +## Actions +These methods invoke a plugin's action. + +```{eval-rst} +.. automethod:: Usage.action +``` + +### Parameter Objects for +These three classes define a deferred action that should be taken by some +interface driver. + +```{eval-rst} +.. autoattribute:: Usage.UsageAction +.. autoclass:: UsageAction +.. autoattribute:: Usage.UsageInputs +.. autoclass:: UsageInputs +.. autoattribute:: Usage.UsageOutputNames +.. autoclass:: UsageOutputNames +``` + +### Results and Assertions +The outputs of are stored in a vanity +class which contain +s. Assertions are performed on these +output variables. + +```{eval-rst} +.. autoclass:: UsageOutputs +.. autoclass:: UsageVariable + :class-doc-from: class + +.. automethod:: UsageVariable.assert_has_line_matching +.. automethod:: UsageVariable.assert_output_type +``` \ No newline at end of file diff --git a/book/plugins/references/api/utils.md b/book/plugins/references/api/utils.md new file mode 100644 index 0000000..79d76a2 --- /dev/null +++ b/book/plugins/references/api/utils.md @@ -0,0 +1,14 @@ +(Util-api-docs)= +# Utilities + +## General Utils +```{eval-rst} +.. autofunction:: qiime2.util.duplicate +.. autofunction:: qiime2.util.redirected_stdio +``` + +## Plugin Utils +```{eval-rst} +.. autofunction:: qiime2.plugin.util.transform +.. autofunction:: qiime2.plugin.util.get_available_cores +``` \ No newline at end of file diff --git a/book/plugins/references/metadata-api.md b/book/plugins/references/metadata-api.md index 6b9355e..d00d162 100644 --- a/book/plugins/references/metadata-api.md +++ b/book/plugins/references/metadata-api.md @@ -1,5 +1,5 @@ (metadata-api)= -# `qiime2.Metadata` API +# User Metadata API This documents the `qiime2.Metadata` API. This may be used by QIIME 2 plugin developers or users of the QIIME 2 Python 3 API. @@ -7,19 +7,25 @@ This may be used by QIIME 2 plugin developers or users of the QIIME 2 Python 3 A ## The `qiime.Metadata` class ```{eval-rst} -.. autofunction:: qiime2.metadata.Metadata +.. autoclass:: qiime2.Metadata + :members: ``` ## Metadata columns ```{eval-rst} -.. autofunction:: qiime2.metadata.MetadataColumn -.. autofunction:: qiime2.metadata.NumericMetadataColumn -.. autofunction:: qiime2.metadata.CategoricalMetadataColumn +.. autoclass:: qiime2.MetadataColumn + :members: + +.. autoclass:: qiime2.NumericMetadataColumn + :members: + +.. autoclass:: qiime2.CategoricalMetadataColumn + :members: ``` ## Exceptions ```{eval-rst} -.. autofunction:: qiime2.metadata.MetadataFileError +.. autoclass:: qiime2.metadata.MetadataFileError ``` \ No newline at end of file