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)
_______________________________________________
Mailing list: https://launchpad.net/~cloud-init-dev
Post to : cloud-init-dev@lists.launchpad.net
Unsubscribe : https://launchpad.net/~cloud-init-dev
More help : https://help.launchpad.net/ListHelp
