Plugin documentation (#155)

* Plugin documentation

I've introduced the plugin system with descriptions and examples for the 4 main kinds of plugins (app/dataset routers, dataset providers, and hook spec). I've also tried to explain the common functionality and enough of the underlying system to get folks started building their own.

* Trying to fix bullet formatting

* Include missing self arg

ht @jr3cermak

* python.version is deprecated

It's likely the source of the version mismatch between docutils and sphinx_rtd_theme making bullets disappear.

xref: readthedocs/sphinx_rtd_theme#1115

* Additional mismatch of theme version

xref: https://stackoverflow.com/questions/67542699/readthedocs-sphinx-not-rendering-bullet-list-from-rst-file/71069918#71069918

.readthedocs.yml

@@ -9,9 +9,13 @@ version: 2
 sphinx:
   configuration: docs/source/conf.py
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
 # Optionally set the version of Python and requirements required to build your docs
 python:
-  version: 3.8
   install:
     - requirements: docs/requirements.txt
     - method: pip

docs/Makefile

@@ -175,3 +175,6 @@ pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+live:
+	sphinx-autobuild -b dirhtml  source/ _build/dirhtml/

docs/requirements.txt

@@ -1,3 +1,4 @@
 sphinx>=3.1
 sphinx-autosummary-accessors
-sphinx_rtd_theme
+sphinx_rtd_theme>=1.0
+autodoc_pydantic

docs/source/api.rst

@@ -8,7 +8,7 @@ Top-level Rest class
 ====================
 
 The :class:`~xpublish.Rest` class can be used for publishing a
-:class:`xarray.Dataset` object or a collection of Dataset objects.
+a collection of :class:`xarray.Dataset` objects.
 
 .. autosummary::
    :toctree: generated/
@@ -18,12 +18,19 @@ The :class:`~xpublish.Rest` class can be used for publishing a
    Rest.cache
    Rest.serve
 
+For serving a single dataset the :class:`~xpublish.SingleDatasetRest` is used instead.
+
+.. autosummary::
+   :toctree: generated/
+
+   SingleDatasetRest
+
 Dataset.rest (xarray accessor)
 ==============================
 
 This accessor extends :py:class:`xarray.Dataset` with the same interface than
-:class:`~xpublish.Rest`. It is a convenient method for publishing one single
-dataset. Proper use of this accessor should be like:
+:class:`~xpublish.Rest` or :class:`~xpublish.SingleDatasetRest`. It is a convenient
+method for publishing one single dataset. Proper use of this accessor should be like:
 
 .. code-block:: python
 
@@ -77,3 +84,22 @@ when creating custom API endpoints.
    get_cache
    get_zvariables
    get_zmetadata
+
+Plugins
+=======
+
+Plugins are inherit from the :class:`~xpublish.Plugin` class, and implement various hooks.
+
+.. currentmodule:: xpublish
+
+.. autosummary::
+   :toctree: generated/
+
+   Plugin
+   hookimpl
+   hookspec
+   Dependencies
+   plugins.hooks.PluginSpec
+   plugins.manage.find_default_plugins
+   plugins.manage.load_default_plugins
+   plugins.manage.configure_plugins

docs/source/conf.py

@@ -43,6 +43,7 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.extlinks',
     'sphinx.ext.napoleon',
+    'sphinxcontrib.autodoc_pydantic',
     'sphinx_autosummary_accessors',
 ]
 

docs/source/index.rst

@@ -67,6 +67,7 @@ API with the following endpoints:
 
    installation
    tutorial
+   plugins
    api
    contributing