docs: Automatically generate module docs form schema if present.

We have started adding jsonschema definitions for cloudconfig modules
(cc_ntp). This branch allows us render sphinx docs using the module's
shema definition instead of using the module's docstring.

This allows us to avoid duplicating schema documentation in the
module-level docstring and schema definition. The corresponding module
documentation is extended a bit to differentiate between config schema and
potential examples.

1 files changed, 10 insertions, 0 deletions

diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py
index 66b3b654..0ea3b6bf 100644
--- a/doc/rtd/conf.py
+++ b/doc/rtd/conf.py
@@ -10,6 +10,7 @@ sys.path.insert(0, os.path.abspath('./'))
 sys.path.insert(0, os.path.abspath('.'))
 
 from cloudinit import version
+from cloudinit.config.schema import get_schema_doc
 
 # Supress warnings for docs that aren't used yet
 # unused_docs = [
@@ -75,3 +76,12 @@ html_theme_options = {
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 html_logo = 'static/logo.png'
+
+def generate_docstring_from_schema(app, what, name, obj, options, lines):
+    """Override module docs from schema when present."""
+    if what == 'module' and hasattr(obj, "schema"):
+        del lines[:]
+        lines.extend(get_schema_doc(obj.schema).split('\n'))
+
+def setup(app):
+    app.connect('autodoc-process-docstring', generate_docstring_from_schema)