From 1025e492412431e95b7ddde46805514e42469db0 Mon Sep 17 00:00:00 2001 From: Chad Smith Date: Mon, 12 Jun 2017 10:39:20 -0600 Subject: 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. --- doc/rtd/conf.py | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'doc') 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) -- cgit v1.2.3