Doc: add sphinx extension for json schema

canonical · Dec 5, 2023 · dfc2a45 · dfc2a45
1 parent bac3d80
commit dfc2a45
Show file tree

Hide file tree

Showing 6 changed files with 25 additions and 8 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
diff --git a/docs/.sphinx/requirements.txt b/docs/.sphinx/requirements.txt
@@ -13,3 +13,4 @@ lxd-sphinx-extensions
 sphinx-copybutton
 myst-parser
 setuptools-scm
+sphinx-jsonschema
diff --git a/docs/conf.py b/docs/conf.py
@@ -52,7 +52,8 @@
     'terminal-output',
     'sphinx_copybutton',
     'sphinxext.opengraph',
-    'myst_parser'
+    'myst_parser',
+    'sphinx-jsonschema'
     ]
 
 myst_enable_extensions = [

diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -10,3 +10,4 @@ Reference
    launcher
    units/index
    snaps
+   submission-schema
diff --git a/docs/reference/submission-schema.rst b/docs/reference/submission-schema.rst
@@ -0,0 +1,17 @@
+.. _submission_schema:
+
+Submission Schema
+==================
+
+Checkbox :ref:`Submission files <submission-files>` provide a summary of the test results and in-depth information that help analyzing the tests. 
+
+This document describes the schema the ``submission.json`` files that's sent to the `Certification website <https://certification.canonical.com>`_ as part of the submission. To get the latest schema definition file in Json, go to the Checkbox `GitHub repository <https://github.com/canonical/checkbox/blob/main/submission-schema/schema.json>`_.
+
+.. important:: 
+
+    The schema described in this document is work-in-progress and being reviewed. If you need assistance in validating the schema, please contact the Checkbox team.
+
+.. jsonschema:: ../../submission-schema/schema.json
+    :lift_definitions:
+    :auto_reference:
+
diff --git a/docs/tutorial/using-checkbox/test-report.rst b/docs/tutorial/using-checkbox/test-report.rst
@@ -133,8 +133,10 @@ in the search bar, you can view all test results related to audio testing.
     The xz compressed tarball is a comprehensive archive that includes the 
     aforementioned reports and all associated attachments, such as I/O logs 
     and binary files. You can extract the tarball with ``tar -xf 
-    sumbission.tar.xz -C /path/to/destination``.
+    submission.tar.xz -C /path/to/destination``.
 
     Certification Website only accepts submissions tarballs, from which it 
     extracts the ``submission.json`` file to create a new test report in the 
-    database. 
+    database. 
+
+For a detailed description of the ``submission.json`` file, see the :doc:`../../reference/submission-schema` reference.