cloud-init-dev team mailing list archive

[Chad Smith <chad.smith@xxxxxxxxxxxxx>]

Chad Smith has proposed merging ~chad.smith/cloud-init:schema-autodoc into cloud-init:master.

Commit message:
docs: Automatically generate module docs form schema attribute if present

We have started adding jsonschema defintions 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.
It allows us to generate our module documentation directly from the schema definition and avoid duplicating that documentation in the module-level docstring. The corresponding module documentation is extended a bit to differentiate between config schema and potential examples.

Requested reviews:
  cloud-init commiters (cloud-init-dev)

For more details, see:
https://code.launchpad.net/~chad.smith/cloud-init/+git/cloud-init/+merge/325507

docs: Automatically generate module docs form schema attribute if present

We have started adding jsonschema defintions 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.
It allows us to generate our module documentation directly from the schema definition and avoid duplicating that documentation in the module-level docstring. The corresponding module documentation is extended a bit to differentiate between config schema and potential examples.


To test:
   tox -e docs
   xdg-open doc/rtd_html/topics/modules.html # look over the cc_ntp module
   # merge this branch and remove part of the module docstring  cloudinit/config/cc_ntp.py
   xdg-open doc/rtd_html/topics/modules.html  # to view the differences in styling and content of cc_ntp
-- 
Your team cloud-init commiters is requested to review the proposed merge of ~chad.smith/cloud-init:schema-autodoc into cloud-init:master.

diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py
index 66b3b65..0ea3b6b 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)