From: Stephen Finucane <stephen@that.guru>
Date: Sat, 27 Oct 2018 00:31:43 +0000 (+0100)
Subject: docs: Integrate API schema into docs
X-Git-Tag: v2.2.0-rc1~150
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=806f1086bf649383e53095220599fd9f564b117b;p=thirdparty%2Fpatchwork.git

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 befd709e..dd2a9e7d 100644
--- 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
index 00000000..bff0dd45
--- /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
index 00000000..a9add8e5
--- /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
index 00000000..e18f8132
--- /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 98c7aa39..f0ca797f 100644
--- 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 ec930ded..a2d02d53 100644
--- 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