Start adding REST API endpoint docs (#196)

* Start adding REST API docs

Works on #55

* Set minimum FastAPI pin due to Path params changing

* Fix filtering of dataset info and add

.gitignore

@@ -128,3 +128,5 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+docs/source/api/generated
+docs/source/api/openapi.json

.readthedocs.yml

@@ -13,6 +13,9 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+  jobs:
+    pre_build:
+      - python docs/source/api/generate_openapi.py
 
 # Optionally set the version of Python and requirements required to build your docs
 python:

docs/requirements.txt

@@ -6,3 +6,4 @@ autodoc_pydantic
 myst-nb
 sphinx-design
 sphinx_github_changelog
+sphinxcontrib-openapi

docs/source/api/contributing.rst

@@ -0,0 +1,138 @@
+========================
+Contributing to Xpublish
+========================
+
+Contributions are highly welcomed and appreciated.  Every little help counts,
+so do not hesitate!
+
+.. contents:: Contribution links
+   :depth: 2
+
+.. _submitfeedback:
+
+Feature requests and feedback
+-----------------------------
+
+Do you like Xpublish? Share some love on Twitter or in your blog posts!
+
+We'd also like to hear about your propositions and suggestions.  Feel free to
+`submit them as issues <https://github.com/xpublish-community/xpublish>`_ and:
+
+* Explain in detail how they should work.
+* Keep the scope as narrow as possible.  This will make it easier to implement.
+
+.. _reportbugs:
+
+Report bugs
+-----------
+
+Report bugs for Xpublish in the `issue tracker <https://github.com/xpublish-community/xpublish>`_.
+
+If you are reporting a bug, please include:
+
+* Your operating system name and version.
+* Any details about your local setup that might be helpful in troubleshooting,
+  specifically the Python interpreter version, installed libraries, and Xpublish
+  version.
+* Detailed steps to reproduce the bug.
+
+If you can write a demonstration test that currently fails but should pass
+(xfail), that is a very useful commit to make as well, even if you cannot
+fix the bug itself.
+
+.. _fixbugs:
+
+Fix bugs
+--------
+
+Look through the `GitHub issues for bugs <https://github.com/xpublish-community/xpublish/labels/type:%20bug>`_.
+
+Talk to developers to find out how you can fix specific bugs.
+
+Write documentation
+-------------------
+
+xpublish could always use more documentation. What exactly is needed?
+
+* More complementary documentation.  Have you perhaps found something unclear?
+* Docstrings.  There can never be too many of them.
+* Blog posts, articles and such -- they're all very appreciated.
+
+You can also edit documentation files directly in the GitHub web interface,
+without using a local copy. This can be convenient for small fixes.
+
+To build the documentation locally, you first need to have a local development environment setup
+by following the the steps in `Preparing Pull Requests <#pull-requests>`__ through the **Install
+dependencies into a new conda environment** step.
+
+You can then build the documentation with the following commands::
+
+    $ conda activate xpublish-dev
+    $ cd docs
+    $ pip install -r requirements.txt
+    $ make html
+
+The built documentation should be available in the ``docs/_build/`` folder.
+
+.. _`pull requests`:
+.. _pull-requests:
+
+Preparing Pull Requests
+-----------------------
+
+#. Fork the
+   `xpublish GitHub repository <https://github.com/xpublish-community/xpublish>`__.  It's
+   fine to use ``xpublish`` as your fork repository name because it will live
+   under your user.
+
+#. Clone your fork locally using `git <https://git-scm.com/>`_ and create a branch::
+
+    $ git clone [email protected]:YOUR_GITHUB_USERNAME/xpublish.git
+    $ cd xpublish
+
+    # now, to fix a bug or add feature create your own branch off "main":
+
+    $ git checkout -b your-bugfix-feature-branch-name main
+
+#. Install `pre-commit <https://pre-commit.com>`_ and its hook on the Xpublish repo::
+
+     $ pip install --user pre-commit
+     $ pre-commit install
+
+   Afterwards ``pre-commit`` will run whenever you commit.
+
+   https://pre-commit.com/ is a framework for managing and maintaining multi-language pre-commit hooks
+   to ensure code-style and code formatting is consistent.
+
+#. Install dependencies into a new conda environment::
+
+    $ conda create -n xpublish-dev
+    $ conda activate xpublish-dev
+    $ pip install -r dev-requirements.txt
+    $ pip install --no-deps -e .
+
+#. Run all the tests
+
+   Now running tests is as simple as issuing this command::
+
+    $ conda activate xpublish-dev
+    $ pytest
+
+   This command will run tests via the "pytest" tool.
+
+#. You can now edit your local working copy and run the tests again as necessary. Please follow PEP-8 for naming.
+
+   When committing, ``pre-commit`` will re-format the files if necessary.
+
+#. Commit and push once your tests pass and you are happy with your change(s)::
+
+    $ git commit -a -m "<commit message>"
+    $ git push -u
+
+#. Finally, submit a pull request through the GitHub website using this data::
+
+    head-fork: YOUR_GITHUB_USERNAME/xpublish
+    compare: your-branch-name
+
+    base-fork: xpublish-community/xpublish
+    base: main

docs/source/api/endpoints.md

@@ -0,0 +1,8 @@
+# API Endpoints
+
+These are all the endpoints that an install of Xpublish with minimal configuration will serve.
+
+```{eval-rst}
+.. openapi:: ./openapi.json
+   :group:
+```

docs/source/api/generate_openapi.py

@@ -0,0 +1,14 @@
+import json
+from pathlib import Path
+
+import xpublish
+
+rest = xpublish.Rest({})
+app = rest.app
+openapi_spec = app.openapi()
+
+script_path = Path(__file__)
+spec_path = script_path.parent / 'openapi.json'
+
+with spec_path.open('w') as f:
+    json.dump(openapi_spec, f)

docs/source/api/included_plugins.md

@@ -0,0 +1,70 @@
+# Included Plugins
+
+Xpublish includes a set of built in plugins with associated endpoints.
+
+```{eval-rst}
+.. currentmodule:: xpublish
+```
+
+## Dataset Info
+
+The dataset info plugin provides a handful of default ways to display datasets and their metadata.
+
+```{eval-rst}
+.. autosummary::
+   :toctree: generated/
+
+   plugins.included.dataset_info.DatasetInfoPlugin
+
+.. openapi:: ./openapi.json
+   :paths:
+    /datasets/{dataset_id}/
+    /datasets/{dataset_id}/keys
+    /datasets/{dataset_id}/dict
+    /datasets/{dataset_id}/info
+```
+
+## Module Version
+
+The module version plugin returns the versions of key libraries powering the Xpublish server.
+
+```{eval-rst}
+.. autosummary::
+   :toctree: generated/
+
+   plugins.included.module_version.ModuleVersionPlugin
+
+.. openapi:: ./openapi.json
+   :include:
+    /versions
+```
+
+## Plugin Info
+
+Similarly the versions of the plugins currently enabled on the Xpublish server.
+
+```{eval-rst}
+.. autosummary::
+   :toctree: generated/
+
+   plugins.included.plugin_info.PluginInfoPlugin
+
+.. openapi:: ./openapi.json
+   :include:
+    /plugins
+```
+
+## Zarr
+
+The Zarr plugin provides consolidated Zarr v2 access to the loaded datasets.
+
+```{eval-rst}
+.. autosummary::
+   :toctree: generated/
+
+   plugins.included.zarr.ZarrPlugin
+
+.. openapi:: ./openapi.json
+   :include:
+    /datasets/{dataset_id}/zarr/*
+```

docs/source/api.md → docs/source/api/index.md

@@ -4,6 +4,15 @@
 
 # API reference
 
+```{toctree}
+---
+hidden:
+---
+endpoints
+included_plugins
+plugins
+```
+
 ## Top-level Rest class
 
 The {class}`~xpublish.Rest` class can be used for publishing a
@@ -136,25 +145,3 @@ passed in to the `Plugin.app_router` or `Plugin.dataset_router` method.
    get_plugins
    get_plugin_manager
 ```
-
-## Plugins
-
-Plugins are inherit from the {class}`~xpublish.Plugin` class, and implement various hooks.
-
-```{eval-rst}
-.. currentmodule:: xpublish
-```
-
-```{eval-rst}
-.. 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/api/plugins.md

@@ -0,0 +1,25 @@
+```{eval-rst}
+.. currentmodule:: xpublish
+```
+
+# Plugins
+
+Plugins are inherit from the {class}`~xpublish.Plugin` class, and implement various hooks.
+
+```{eval-rst}
+.. currentmodule:: xpublish
+```
+
+```{eval-rst}
+.. 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

@@ -49,6 +49,7 @@
     'sphinx_design',
     'myst_parser',
     'sphinx_github_changelog',
+    'sphinxcontrib.openapi',
 ]
 
 myst_enable_extensions = []

docs/source/index.md

@@ -62,7 +62,7 @@ with useful background information and explanation.
 ```
 
 ```{grid-item-card} API Reference
-:link: api
+:link: api/index
 :link-type: doc
 
 The reference guide contains a detailed description of the Xpublish API/
@@ -109,7 +109,7 @@ maxdepth: 2
 ---
 getting-started/index
 user-guide/index
-api
+api/index
 ecosystem/index
 Contributing <contributing>
 changelog

pyproject.toml

@@ -53,7 +53,7 @@ known-third-party = [
 
 [tool.ruff.flake8-bugbear]
 # Allow fastapi.Depends and other dependency injection style function arguments
-extend-immutable-calls = ["fastapi.Depends", "fastapi.Query"]
+extend-immutable-calls = ["fastapi.Depends", "fastapi.Query", "fastapi.Path"]
 
 [tool.pytest.ini_options]
 log_cli = true

requirements.txt

@@ -1,6 +1,6 @@
 cachey
 dask
-fastapi
+fastapi>=0.78.0
 numcodecs
 numpy
 pluggy