-
Notifications
You must be signed in to change notification settings - Fork 880
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Doc module render fixes #5562
Doc module render fixes #5562
Conversation
79934b6
to
55baa0a
Compare
…ical#5562) Also emphasize ''users''.
…ical#5562) Without this fix, rendered module documentation was not rendering the following text for some objects: Each object in **<key_name>** list supports the following keys: See Rsyslog Config schema tab.
…cal#5562) Document any keys of objects in a list which allows for objects as one of the alternative types allowed as a list item. Also, when documenting properties, ensure we skip documentation of either 'properties' or 'patternProperties' if those properties are declared in the hidden key. Fixes canonicalGH-5514
…5562) When running tox -e doc the following environment variables are supported: CLOUD_INIT_DEBUG_MODULE_DOC=cc_<module_id> CLOUD_INIT_DEBUG_MODULE_DOC_FILE=<file_path> The env var CLOUD_INIT_DEBUG_MODULE_DOC can be set to either a specific module id, such as cc_rsyslog, or 'all'. When set the rendered module documentation RST format is printed inline to stdout to allow for quick analysis of rendered content. Optionally, if CLOUD_INIT_DEBUG_MODULE_DOC_FILE is set to a writable file path, the output of the rendered content is written to that file instead. This supports development of docs and quick comparison of docs generated before and after a changeset.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
see @s-makin's comment
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 -%} |
…ical#5562) Without this fix, rendered module documentation was not rendering the following text for some objects: Each object in **<key_name>** list supports the following keys: See Rsyslog Config schema tab.
55baa0a
to
fb0dca5
Compare
…cal#5562) Document any keys of objects in a list which allows for objects as one of the alternative types allowed as a list item. Also, when documenting properties, ensure we skip documentation of either 'properties' or 'patternProperties' if those properties are declared in the hidden key. Fixes canonicalGH-5514
…5562) When running tox -e doc the following environment variables are supported: CLOUD_INIT_DEBUG_MODULE_DOC=cc_<module_id> CLOUD_INIT_DEBUG_MODULE_DOC_FILE=<file_path> The env var CLOUD_INIT_DEBUG_MODULE_DOC can be set to either a specific module id, such as cc_rsyslog, or 'all'. When set the rendered module documentation RST format is printed inline to stdout to allow for quick analysis of rendered content. Optionally, if CLOUD_INIT_DEBUG_MODULE_DOC_FILE is set to a writable file path, the output of the rendered content is written to that file instead. This supports development of docs and quick comparison of docs generated before and after a changeset.
fb0dca5
to
64d6402
Compare
…ical#5562) Also emphasize ''users''.
…ical#5562) Without this fix, rendered module documentation was not rendering the following text for some objects: Each object in **<key_name>** list supports the following keys: See Rsyslog Config schema tab.
…cal#5562) Document any keys of objects in a list which allows for objects as one of the alternative types allowed as a list item. Also, when documenting properties, ensure we skip documentation of either 'properties' or 'patternProperties' if those properties are declared in the hidden key. Fixes canonicalGH-5514
…5562) When running tox -e doc the following environment variables are supported: CLOUD_INIT_DEBUG_MODULE_DOC=cc_<module_id> CLOUD_INIT_DEBUG_MODULE_DOC_FILE=<file_path> The env var CLOUD_INIT_DEBUG_MODULE_DOC can be set to either a specific module id, such as cc_rsyslog, or 'all'. When set the rendered module documentation RST format is printed inline to stdout to allow for quick analysis of rendered content. Optionally, if CLOUD_INIT_DEBUG_MODULE_DOC_FILE is set to a writable file path, the output of the rendered content is written to that file instead. This supports development of docs and quick comparison of docs generated before and after a changeset.
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 |
5c82e6c
to
cd2030a
Compare
cd2030a
to
528af6a
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 :)
…ical#5562) Also emphasize ''users''.
…ical#5562) Without this fix, rendered module documentation was not rendering the following text for some objects: Each object in **<key_name>** list supports the following keys: See Rsyslog Config schema tab.
…cal#5562) Document any keys of objects in a list which allows for objects as one of the alternative types allowed as a list item. Also, when documenting properties, ensure we skip documentation of either 'properties' or 'patternProperties' if those properties are declared in the hidden key. Fixes canonicalGH-5514
…5562) When running tox -e doc the following environment variables are supported: CLOUD_INIT_DEBUG_MODULE_DOC=cc_<module_id> CLOUD_INIT_DEBUG_MODULE_DOC_FILE=<file_path> The env var CLOUD_INIT_DEBUG_MODULE_DOC can be set to either a specific module id, such as cc_rsyslog, or 'all'. When set the rendered module documentation RST format is printed inline to stdout to allow for quick analysis of rendered content. Optionally, if CLOUD_INIT_DEBUG_MODULE_DOC_FILE is set to a writable file path, the output of the rendered content is written to that file instead. This supports development of docs and quick comparison of docs generated before and after a changeset.
528af6a
to
5b257a4
Compare
@holmanb I rebased against main to resolve merge conflicts. If you get a chance can we peek at this please. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM, thanks @blackboxsw!
5b257a4
to
a657f07
Compare
Without this fix, rendered module documentation was not rendering the following text for some objects: Each object in **<key_name>** list supports the following keys: See Rsyslog Config schema tab.
Document any keys of objects in a list which allows for objects as one of the alternative types allowed as a list item. Also, when documenting properties, ensure we skip documentation of either 'properties' or 'patternProperties' if those properties are declared in the hidden key. Fixes GH-5514
When running tox -e doc the following environment variables are supported: CLOUD_INIT_DEBUG_MODULE_DOC=cc_<module_id> CLOUD_INIT_DEBUG_MODULE_DOC_FILE=<file_path> The env var CLOUD_INIT_DEBUG_MODULE_DOC can be set to either a specific module id, such as cc_rsyslog, or 'all'. When set the rendered module documentation RST format is printed inline to stdout to allow for quick analysis of rendered content. Optionally, if CLOUD_INIT_DEBUG_MODULE_DOC_FILE is set to a writable file path, the output of the rendered content is written to that file instead. This supports development of docs and quick comparison of docs generated before and after a changeset.
Fix incorrectly redacted module property documentation for
Users and Groups
andRsyslog
for nested JSON schemas which contain alternativeoneOf
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:
To render all module docs
CLOUD_INIT_DEBUG_MODULE_DOC=all
can be provided insteadProposed Commit Message
--- See individual commits
Additional Context
Test Steps
Merge type