cloud-init icon indicating copy to clipboard operation
cloud-init copied to clipboard

Docs module generation from YAML instead of python meta dicts

Open blackboxsw opened this issue 1 year ago • 1 comments

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_ refactors to templates, the thing to be wary of is that our json schema inline RST syntax doesn't get rendered with poor formatting in the generated docs, or disappear from output of the 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_ at a time to ease reviewing.

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

blackboxsw avatar May 09 '24 04:05 blackboxsw

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

blackboxsw avatar May 11 '24 02:05 blackboxsw