Docs module generation from YAML instead of python meta dicts
rebase individual commits
Primary functional commit with cc_ansible doc template migration followed by minor integration test helper and doc migrations of apt_configure/apt_pipelining, bootcmd and byobu. The intent and migration will be basically the same for every cc_ module once this lands. I expect 3 more branches of just cc_cloud-init schema --docs cc_<mod_name>
feat(docs): generate rtd module schema from rtd/module-docs
Add a new doc/rtd/templates and doc/module-docs directory for
which use sphinxcontrib.datatemplates to render schema documentation
instead of automodule documentation.
The refactor allows moving doc-related keys out of each cc_* module's
meta dictionary: examples, descripton, name and title.
Move doc-related metadata keys into
doc/module-docs/<module_id>/data.yaml and supporting examples into
doc/module-docs/<module_id>/example*.yaml.
This allows us to simplify cc_<module> documentation by allowing
doc authors to manipulate either sphinx jinja templates, RST files or
YAML example files instead of having to dedent and encode RST or MD
markup in python "meta" dictionarties.
To support doc generation for both readthedocs(sphinx) and cloud-init
schema --docs command, schema.py grows a get_module_docs function to
source the specific module-docs/*/data.yaml files for examples, names
and titles.
The intent with this draft is to start a conversation about relocating RST templates out of cloudinit.config.schema and into official templates in doct/rtd/templates that could be more easily updated if we change skins.
This only sets up common logic for generating RTD docs and sharing the module-docs/*.yaml with cloud-init schema --doc command line. If we decide this is a reasonable approach, this branch will likely adapt a few cc_
Benefits:
- move docs into YAML data files so module developers don't have to encode RST in python dicts for examples/descriptions/titles etc
- python cc_
s longer do work of load for setting __doc__ = get_meta_doc()on module load which reads cloud-config-schema.json
ok this PR is ready for review. Best way to test the branch is to either:
- compare public docs against tox -e doc; xdg-open ./docs/rtd_html/referece/modules.html
--- OR ---
CLOUD_INIT_KEEP_INSTANCE=1 CLOUD_INIT_CLOUD_INIT_SOURCE=IN_PLACE tox -e integration-tests -- tests/integration_tests/test_logging.py
lxc exec cloudinit.... -- cloud-init schema --docs cc_ansible