Add static openapi docs to sphinx site

docs/api_spec.md

@@ -0,0 +1,17 @@
+# REST API Spec
+
+This is the spec for package version version **{{ env.config.version }}**,
+exported from FastAPI in `conf.py` as follows
+
+```python
+import yaml
+from pangeo_forge_orchestrator.api import api
+
+api_spec = api.openapi()
+with open("openapi.yaml", mode='w') as fp:
+    yaml.dump(api_spec, fp)
+```
+
+```{eval-rst}
+.. openapi:: openapi.yaml
+```

docs/conf.py

@@ -1,9 +1,17 @@
 # Compare: https://github.com/pangeo-forge/pangeo-forge-recipes/blob/master/docs/conf.py
+from importlib.metadata import version as _get_version
+
+import yaml
+
+from pangeo_forge_orchestrator.api import api
+
+version = _get_version("pangeo_forge_orchestrator")
+
 
 # -- Project information -----------------------------------------------------
 
 project = "Pangeo Forge Orchestrator"
-copyright = "2021, Pangeo Community"
+copyright = "2022, Pangeo Community"
 author = "Pangeo Community"
 
 # -- General configuration ---------------------------------------------------
@@ -15,8 +23,11 @@
     # "numpydoc",
     "sphinx_autodoc_typehints",
     "sphinx_copybutton",
+    "sphinxcontrib.openapi",
 ]
 
+myst_enable_extensions = ["substitution"]
+
 extlinks = {
     "issue": ("https://github.com/pangeo-forge/pangeo-forge-orchestrator/issues/%s", "GH issue "),
     "pull": ("https://github.com/pangeo-forge/pangeo-forge-orchestrator/pull/%s", "GH PR "),
@@ -45,3 +56,10 @@
 html_static_path = ["_static"]
 
 myst_heading_anchors = 2
+
+
+# write out the openapi spec to a yaml file
+api_spec = api.openapi()
+with open("openapi.yaml", mode="w") as fp:
+    yaml.dump(api_spec, fp)
+# this is read in api_spec.md

docs/index.md

@@ -9,5 +9,6 @@ You have found the documentation for for `pangeo-forge-orchestrator`, an unrelea
 ```{toctree}
 :maxdepth: 1
 
+api_spec
 development_guide
 ```

docs/requirements.txt

@@ -4,4 +4,6 @@ myst-parser==0.13.6
 myst-nb==0.12.3
 sphinx-copybutton==0.3.1
 sphinx-autodoc-typehints
+sphinxcontrib-openapi
+uvicorn
 .

setup.cfg

@@ -59,7 +59,7 @@ max-line-length = 100
 
 [isort]
 known_first_party=pangeo_forge_orchestrator
-known_third_party=fastapi,pydantic,pytest,pytest_lazyfixture,requests,setuptools,sqlalchemy,sqlmodel,typer
+known_third_party=fastapi,pydantic,pytest,pytest_lazyfixture,requests,setuptools,sqlalchemy,sqlmodel,typer,yaml
 multi_line_output=3
 include_trailing_comma=True
 force_grid_wrap=0