docs: Integrate API schema into docs

This takes advantage of the sphinxcontrib-openapi Sphinx extension,
which allows us to embed the REST API documentation into our docs quite
nicely.

Signed-off-by: Stephen Finucane <stephen@that.guru>

diff --git a/docs/api/rest/index.rst b/docs/api/rest/index.rst
index befd709e2795ee8417f03c768115ffd6bbe36c55..dd2a9e7d31f83eba0d50b068483a281528826d66 100644 (file)
--- a/docs/api/rest/index.rst
+++ b/docs/api/rest/index.rst
@@ -12,6 +12,8 @@ exposed by the API, refer to the web browsable API. This can be found at:
 
 where `patchwork.example.com` refers to the URL of your Patchwork instance.
 
+If all you want is reference guides, skip straight to :ref:`rest-api-schemas`.
+
 .. important::
 
    The REST API can be enabled/disabled by the administrator: it may not be
@@ -265,6 +267,18 @@ Supported Versions
 Further information about this and more can typically be found in
 :doc:`the release notes </releases/index>`.
 
+.. _rest-api-schemas:
+
+Schemas
+-------
+
+Auto-generated schema documentation is provided below.
+
+.. toctree::
+
+   /api/rest/schemas/v1.0
+   /api/rest/schemas/v1.1
+
 .. Links
 
 .. _curl: https://curl.haxx.se/

diff --git a/docs/api/rest/schemas/index.rst b/docs/api/rest/schemas/index.rst
new file mode 100644 (file)
index 0000000..bff0dd4
--- /dev/null
+++ b/docs/api/rest/schemas/index.rst
@@ -0,0 +1,13 @@
+:orphan:
+
+Schemas
+=======
+
+The APIs for the :doc:`REST API </api/rest/index>` are listed below. For
+further information, refer to the :doc:`REST API overview </api/rest/index>`.
+
+.. toctree::
+   :maxdepth: 2
+
+   /api/rest/schemas/v1.0
+   /api/rest/schemas/v1.1

diff --git a/docs/api/rest/schemas/v1.0.rst b/docs/api/rest/schemas/v1.0.rst
new file mode 100644 (file)
index 0000000..a9add8e
--- /dev/null
+++ b/docs/api/rest/schemas/v1.0.rst
@@ -0,0 +1,5 @@
+API v1.0
+========
+
+.. openapi:: ../../schemas/v1.0/patchwork.yaml
+   :examples:

diff --git a/docs/api/rest/schemas/v1.1.rst b/docs/api/rest/schemas/v1.1.rst
new file mode 100644 (file)
index 0000000..e18f813
--- /dev/null
+++ b/docs/api/rest/schemas/v1.1.rst
@@ -0,0 +1,5 @@
+API v1.1 (latest)
+=================
+
+.. openapi:: ../../schemas/v1.1/patchwork.yaml
+   :examples:

diff --git a/docs/conf.py b/docs/conf.py
index 98c7aa39fd66469567319d5074897dadeb39d318..f0ca797f6dac07668dda54080e213b80a09b1ac1 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -20,7 +20,11 @@ needs_sphinx = '1.5'
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.todo', 'reno.sphinxext']
+extensions = [
+    'sphinx.ext.todo',
+    'reno.sphinxext',
+    'sphinxcontrib.openapi'
+]
 
 # The theme to use for HTML and HTML Help pages.
 html_theme = 'sphinx_rtd_theme'

diff --git a/docs/requirements.txt b/docs/requirements.txt
index ec930dedd6f832e0e3567120025b1f200ed107b0..a2d02d5392121d17b116544935523a7c0e779a18 100644 (file)
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -2,3 +2,4 @@ sphinx>=1.5
 reno>=2.2
 sphinx_rtd_theme==0.4.2
 jinja2==2.10
+sphinxcontrib-openapi==0.4.0