Plugin API Docs

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;
 }

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 🧩"

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).

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
 

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 <project:#CitationRecord> and lists of them
+(<inv:python:py:class:#list> and <project:#Citations>).
+
+
+```{eval-rst}
+.. autoclass:: qiime2.plugin.Citations
+   :members:
+   :special-members: __iter__
+
+.. autoclass:: qiime2.plugin.CitationRecord
+```

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
+
+```

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
+```

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
+```

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 <project:#Plugin> 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
+```

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
+
+```