Doc module render fixes

[blackboxsw]

Fix incorrectly redacted module property documentation for Users and Groups and Rsyslog for nested JSON schemas which contain alternative oneOf schemas.

The bulk of this work was made easier by adding the ability to debug the rendered RST files to see bogus white-space indentation that sphinx was able to smooth out.

When building docs, a developer/reviewer can now look at individually rendered RST content for any config module with the following environment variable:

CLOUD_INIT_DEBUG_MODULE_DOC_FILE=/tmp/doc.cc_rsyslog CLOUD_INIT_DEBUG_MODULE_DOC=cc_rsyslog tox -e doc

To render all module docs CLOUD_INIT_DEBUG_MODULE_DOC=all can be provided instead

Proposed Commit Message

--- See individual commits

Additional Context

Test Steps

tox -e doc
xdg-open doc/rtd_html/reference/modules.html   # Navigate to rsyslog and "users and groups" schema tabs to compare local render versus public docs for the same schema tabs

Merge type

• Squash merge using "Proposed Commit Message"
• Rebase and merge unique commits. Requires commit messages per-commit each referencing the pull request number (#<PR_NUM>)

[s-makin]

Overall this looks like a big visual improvement alongside the missing keys being back. The only issue I can see is that in deeper levels, there is a missing newline (Ansible is conveniently the first example!) so that it looks like keys are missing (they're stuck on the previous line:

[holmanb]

see @s-makin's comment

[blackboxsw]

CLOUD_INIT_DEBUG_MODULE_DOC_FILE=/tmp/doc.cc_rsyslog CLOUD_INIT_DEBUG_MODULE_DOC=cc_rsyslog tox -e doc

Thanks @s-makin. I hadn't realized I got a bit greedy with my jinja template newline chomping at the end of each rendered content in the module_property.tmpl. The following diff fixes this:

--- a/doc/rtd/templates/module_property.tmpl
+++ b/doc/rtd/templates/module_property.tmpl
@@ -1,7 +1,7 @@
 {% macro print_prop(name, types, description, prefix) -%}
 {% set descr_suffix = description.splitlines()[0]|d('') -%}
 {% set descr_lines = description.splitlines()[1:]|d([]) -%}
-{{prefix}}* **{{name}}:** ({{types}}){{ descr_suffix -}}
+{{prefix}}* **{{name}}:** ({{types}}){{ descr_suffix }}
 {% for line in descr_lines -%}
 {{prefix ~ '  '}}{{ line }}
 {% endfor -%}

[blackboxsw]

Pushed two extra commits here that don't have to be in this review. But the intent is to avoid using italics for our entire deprecated key messaging as the deprecated descriptions typically use RST to emphasize the preferred new key resulting in a poorly rendered message like the attached image below

[blackboxsw]

Pushed two extra commits here that don't have to be in this review. But the intent is to avoid using italics for our entire deprecated key messaging as the deprecated descriptions typically use RST to emphasize the preferred new key resulting in a poorly rendered message like the attached image below

With the most recent 2 commits added, the rendered formatting with an italicized Deprecated prefix and bold looks like the following:

[s-makin]

Thanks for the changes. Haven't spotted any more wrongly-formatted bullet lists. The only inconsistencies now come from the individual files that the docs are generated from, and it's beyond the scope of this PR to fix those so happy to see this merged :)

[blackboxsw]

@holmanb I rebased against main to resolve merge conflicts. If you get a chance can we peek at this please.

[holmanb]

LGTM, thanks @blackboxsw!