Docs revamp

Start of a big revamp of the docs.
- Uses Pydata theme
- Enables MyST markdown and converts a lot of the docs to it (rst heading levels and git conflict formatting conflict, which was a fun discovery)
- Re-arranges things along the Diátaxis framework lines, or at least how they are being used in the PyData space
- Adds the vision or 'Why Xpublish' page
- Breaks the tutorial into sections and scaffolds sections for use of plugins

Closes xpublish-community#163 xpublish-community#165 xpublish-community#162 xpublish-community#166

docs/requirements.txt

@@ -3,3 +3,5 @@ sphinx-autosummary-accessors
 pydata-sphinx-theme
 sphinx-autodoc-typehints
 autodoc_pydantic
+myst-nb
+sphinx-design

docs/source/api.rst → docs/source/api.md

@@ -1,17 +1,17 @@
+```{eval-rst}
 .. currentmodule:: xpublish
+```
 
-#############
-API reference
-#############
+# API reference
 
-Top-level Rest class
-====================
+## 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.
+The {class}`~xpublish.Rest` class can be used for publishing a
+{class}`xarray.Dataset` object or a collection of Dataset objects.
 
 The main interfaces to Xpublish that many users may use.
 
+```{eval-rst}
 .. autosummary::
    :toctree: generated/
 
@@ -22,11 +22,13 @@ The main interfaces to Xpublish that many users may use.
    Rest.serve
    Rest.register_plugin
    Rest.dependencies
+```
 
 There are also a handful of methods that are more likely to be used
 when subclassing `xpublish.Rest` to modify functionality, or are used
 by plugin dependencies.
 
+```{eval-rst}
 .. autosummary::
    :toctree: generated/
 
@@ -37,78 +39,92 @@ by plugin dependencies.
    Rest.init_cache_kwargs
    Rest.init_app_kwargs
    Rest.plugin_routers
+```
 
-There is also a specialized version of :class:`xpublish.Rest` for use
+There is also a specialized version of {class}`xpublish.Rest` for use
 when only a single dataset is being served, instead of a collection
 of datasets.
 
+```{eval-rst}
 .. autosummary::
    :toctree: generated/
 
    SingleDatasetRest
    SingleDatasetRest.setup_datasets
+```
 
-For serving a single dataset the :class:`~xpublish.SingleDatasetRest` is used instead.
+For serving a single dataset the {class}`~xpublish.SingleDatasetRest` is used instead.
 
+```{eval-rst}
 .. autosummary::
    :toctree: generated/
 
    SingleDatasetRest
+```
 
-Dataset.rest (xarray accessor)
-==============================
+## Dataset.rest (xarray accessor)
 
-This accessor extends :py:class:`xarray.Dataset` with the same interface than
-:class:`~xpublish.SingleDatasetRest`. It is a convenient method for publishing one single
+This accessor extends {py:class}`xarray.Dataset` with the same interface than
+{class}`~xpublish.SingleDatasetRest`. It is a convenient method for publishing one single
 dataset. Proper use of this accessor should be like:
 
-.. code-block:: python
-
-   >>> import xarray as xr         # first import xarray
-   >>> import xpublish             # import xpublish (the dataset 'rest' accessor is registered)
-   >>> ds = xr.Dataset()           # create or load an xarray Dataset
-   >>> ds.rest(...)                # call the 'rest' accessor on the dataset
-   >>> ds.rest.<meth_or_prop>      # access to the methods and properties listed below
+```python
+>>> import xarray as xr         # first import xarray
+>>> import xpublish             # import xpublish (the dataset 'rest' accessor is registered)
+>>> ds = xr.Dataset()           # create or load an xarray Dataset
+>>> ds.rest(...)                # call the 'rest' accessor on the dataset
+>>> ds.rest.<meth_or_prop>      # access to the methods and properties listed below
+```
 
+```{eval-rst}
 .. currentmodule:: xarray
+```
 
 **Calling the accessor**
 
+```{eval-rst}
 .. autosummary::
    :toctree: generated/
    :template: autosummary/accessor_callable.rst
 
    Dataset.rest
+```
 
 **Properties**
 
+```{eval-rst}
 .. autosummary::
    :toctree: generated/
    :template: autosummary/accessor_attribute.rst
 
    Dataset.rest.app
    Dataset.rest.cache
+```
 
 **Methods**
 
+```{eval-rst}
 .. autosummary::
    :toctree: generated/
    :template: autosummary/accessor_method.rst
 
    Dataset.rest.serve
+```
 
-FastAPI dependencies
-====================
+## FastAPI dependencies
 
-The functions below are defined in module ``xpublish.dependencies`` and can
-be used as `FastAPI dependencies <https://fastapi.tiangolo.com/tutorial/dependencies>`_
+The functions below are defined in module `xpublish.dependencies` and can
+be used as [FastAPI dependencies](https://fastapi.tiangolo.com/tutorial/dependencies)
 when creating custom API endpoints directly.
 
-When creating routers with plugins, instead use ``xpublish.Dependency`` that will be
-passed in to the ``Plugin.app_router`` or ``Plugin.dataset_router`` method.
+When creating routers with plugins, instead use `xpublish.Dependency` that will be
+passed in to the `Plugin.app_router` or `Plugin.dataset_router` method.
 
+```{eval-rst}
 .. currentmodule:: xpublish.dependencies
+```
 
+```{eval-rst}
 .. autosummary::
    :toctree: generated/
 
@@ -119,13 +135,17 @@ passed in to the ``Plugin.app_router`` or ``Plugin.dataset_router`` method.
    get_zmetadata
    get_plugins
    get_plugin_manager
+```
 
-Plugins
+## Plugins
 
-Plugins are inherit from the :class:`~xpublish.Plugin` class, and implement various hooks.
+Plugins are inherit from the {class}`~xpublish.Plugin` class, and implement various hooks.
 
+```{eval-rst}
 .. currentmodule:: xpublish
+```
 
+```{eval-rst}
 .. autosummary::
    :toctree: generated/
 
@@ -137,3 +157,4 @@ Plugins are inherit from the :class:`~xpublish.Plugin` class, and implement vari
    plugins.manage.find_default_plugins
    plugins.manage.load_default_plugins
    plugins.manage.configure_plugins
+```

docs/source/conf.py

@@ -46,8 +46,13 @@
     'sphinxcontrib.autodoc_pydantic',
     'sphinx_autosummary_accessors',
     'sphinx_autodoc_typehints',
+    'sphinx_design',
+    'myst_parser',
 ]
 
+myst_enable_extensions = ['colon_fence']
+myst_heading_anchors = 6
+
 extlinks = {
     'issue': ('https://github.com/xarray-contrib/xpublish/issues/%s', 'GH#'),
     'pr': ('https://github.com/xarray-contrib/xpublish/pull/%s', 'GH#'),

docs/source/ecosystem/index.md

@@ -0,0 +1,25 @@
+# Ecosystem
+
+Xpublish's ecosystem is made up of plugins and servers, and the folks who build and run them.
+
+## Connect
+
+We have two main venues for discussing Xpublish and it's ecosystem, Github Discussions and Slack.
+
+### Github Discussions
+
+For longer form discussions, we can be found in [Github Discussions](https://github.com/xarray-contrib/xpublish/discussions?discussions_q=).
+
+### Slack
+
+Xpublish has a channel (`#xpublish`) on [ESIP](https://www.esipfed.org/)'s (Earth Science Information Partners) Slack. (Insert Rich's justification here about ESIP being the biggest unbrella that he can find) [Join here](https://join.slack.com/t/esip-all/shared_invite/zt-1omjufm9z-iH8Gf7gmmsm2SiS5Xh6BlQ)
+
+## Server distributions
+
+- [XREDS](https://github.com/asascience-open/xreds) from RPS
+
+## Plugins
+
+- [OGC EDR](https://github.com/gulfofmaine/xpublish-edr/)
+- [OpenDAP](https://github.com/gulfofmaine/xpublish-opendap/)
+- [WMS](https://github.com/asascience-open/xpublish-wms)

docs/source/getting-started/index.md

@@ -0,0 +1,12 @@
+# Getting started
+
+The getting started guide aims to get you using Xpublish productively as quickly as possible.
+It is designed as an entry point for new users, and it provided an introduction to Xpublish’s main concepts.
+
+```{toctree}
+:hidden:
+
+why-xpublish
+installation
+tutorial/index
+```

docs/source/getting-started/tutorial/dataset-provider-plugin.md

@@ -0,0 +1,6 @@
+# Building a dataset provider plugin
+
+```{warning}
+Under construction.
+For now see the [plugin user guide](../../user-guide/plugins.rst)
+```

docs/source/getting-started/tutorial/dataset-router-plugin.md

@@ -0,0 +1,6 @@
+# Creating a dataset router plugin
+
+```{warning}
+Under construction.
+For now see the [plugin user guide](../../user-guide/plugins.rst)
+```

docs/source/getting-started/tutorial/dataset-router.md

@@ -0,0 +1,43 @@
+# Building a dataset router
+
+It is also possible to create custom API routes and serve them via Xpublish. In
+the example below, we create a minimal application to get the mean value of a
+given variable in the published dataset:
+
+```python
+from fastapi import APIRouter, Depends, HTTPException
+from xpublish.dependencies import get_dataset
+
+
+myrouter = APIRouter()
+
+@myrouter.get("/{var_name}/mean")
+def get_mean(var_name: str, dataset: xr.Dataset = Depends(get_dataset)):
+    if var_name not in dataset.variables:
+        raise HTTPException(
+            status_code=404, detail=f"Variable '{var_name}' not found in dataset"
+        )
+
+    return float(dataset[var_name].mean())
+
+ds.rest(routers=[myrouter])
+
+ds.rest.serve()
+```
+
+Taking the dataset loaded above in this tutorial, this application should behave
+like this:
+
+- `/air/mean` returns a floating number
+- `/not_a_variable/mean` returns a 404 HTTP error
+
+The {func}`~xpublish.dependencies.get_dataset` function in the example above is
+a FastAPI dependency that is used to access the dataset object being served by
+the application, either from inside a FastAPI path operation decorated function
+or from another FastAPI dependency. Note that `get_dataset` can only be used
+as a function argument (FastAPI has other ways to reuse a dependency, but those
+are not supported in this case).
+
+Xpublish also provides a {func}`~xpublish.dependencies.get_cache` dependency
+function to get/put any useful key-value pair from/into the cache that is
+created along with a running instance of the application.

docs/source/getting-started/tutorial/index.md

@@ -0,0 +1,16 @@
+# Tutorial
+
+The Xpublish tutorial is designed for an experienced Xarray user (but not a server administrator) to be able to start at the beginning and build layers of understanding of how Xpublish and it's ecosystem work together.
+
+If you are interested in developing plugins or administering servers, you may want to jump ahead to [using plugins](./using-plugins.md) or look to [deployment](../../user-guide/deployment/index.md) in the user guide..
+
+```{toctree}
+:hidden:
+
+introduction
+dataset-router
+serving-multiple-datasets
+using-plugins
+dataset-router-plugin
+dataset-provider-plugin
+```