From 806f1086bf649383e53095220599fd9f564b117b Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Sat, 27 Oct 2018 01:31:43 +0100 Subject: 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 --- docs/api/rest/index.rst | 14 ++++++++++++++ docs/api/rest/schemas/index.rst | 13 +++++++++++++ docs/api/rest/schemas/v1.0.rst | 5 +++++ docs/api/rest/schemas/v1.1.rst | 5 +++++ 4 files changed, 37 insertions(+) create mode 100644 docs/api/rest/schemas/index.rst create mode 100644 docs/api/rest/schemas/v1.0.rst create mode 100644 docs/api/rest/schemas/v1.1.rst (limited to 'docs/api') diff --git a/docs/api/rest/index.rst b/docs/api/rest/index.rst index befd709..dd2a9e7 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 `. +.. _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 0000000..bff0dd4 --- /dev/null +++ b/docs/api/rest/schemas/index.rst @@ -0,0 +1,13 @@ +:orphan: + +Schemas +======= + +The APIs for the :doc:`REST API ` are listed below. For +further information, refer to the :doc:`REST API overview `. + +.. 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 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 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: -- cgit v1.2.3