Adapt doc generation to new CAPI2 JSON Schema definition (#626)

Adapt doc generation to new CAPI2 JSON Schema definition

Author: erikwa

.readthedocs.yml

@@ -11,7 +11,7 @@ formats: all
 
 # Optionally set the version of Python and requirements required to build your docs
 python:
-  version: 3
+  version: 3.8
   install:
     - requirements: doc/requirements.txt
     - method: pip

doc/requirements.txt

@@ -1,3 +1,3 @@
-Sphinx >= 3.0
+Sphinx >= 6.2.1
 sphinx-rtd-theme
 sphinxcontrib-programoutput

doc/source/conf.py

@@ -14,8 +14,11 @@
 from datetime import datetime
 from distutils.version import LooseVersion
 
+import jsonschema2md
+
 import fusesoc
-from fusesoc.capi2.core import gen_doc
+from fusesoc.capi2.json_schema import capi2_schema
+from fusesoc.utils import yaml_read
 
 # -- Path setup --------------------------------------------------------------
 
@@ -56,6 +59,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinxcontrib.programoutput",
+    "myst_parser",
 ]
 
 intersphinx_mapping = {"https://docs.python.org/3": None}
@@ -67,8 +71,7 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = [".rst", ".md"]
 
 # The master toctree document.
 master_doc = "index"
@@ -203,7 +206,11 @@
 
 # -- Extension configuration -------------------------------------------------
 
+p = jsonschema2md.Parser(
+    examples_as_yaml=False,
+    show_examples="all",
+)
+md_lines = p.parse_schema(yaml_read(capi2_schema))
 
-s = gen_doc()
-with open(os.path.join(os.path.abspath("."), "ref/capi2.rst"), "w") as f:
-    f.write(s)
+with open(os.path.join(os.path.abspath("."), "ref/capi2.md"), "w") as f:
+    f.write("".join(md_lines))

doc/source/ref/index.rst

@@ -6,6 +6,6 @@ FuseSoC Reference Manual
    :maxdepth: 2
    :caption: Contents
 
-   capi2.rst
+   capi2.md
    migrations.rst
    glossary.rst

setup.py

@@ -56,6 +56,8 @@ def read(fname):
         "pyyaml",
         "simplesat>=0.8.0",
         "fastjsonschema",
+        "jsonschema2md",
+        "myst_parser",
     ],
     # Supported Python versions: 3.6+
     python_requires=">=3.6, <4",

tox.ini

@@ -55,16 +55,16 @@ description = Automatically (re-)build the HTML documentation with Sphinx
 deps =
     -rdoc/requirements.txt
     sphinx-autobuild
+    myst_parser
+    jsonschema2md
 commands =
-    # capi2.rst is generated during the documentation build and would
+    # capi2.md is generated during the documentation build and would
     # immediately re-trigger a build. We ignore the generated file, and instead
-    # watch the primary source of information for the generated file. Since
-    # capi2.rst is also produced from some other files this check isn't fully
-    # exhaustive, but covers most use cases.
+    # watch the primary source of information for the generated file.
     sphinx-autobuild \
         --open-browser \
         -d "{toxworkdir}/docs_doctree" \
-        --ignore "*/doc/source/ref/capi2.rst" \
+        --ignore "*/doc/source/ref/capi2.md" \
         --watch "fusesoc/capi2" \
         doc/source \
         "{toxworkdir}/docs_out" \