Fix ansible-doc rendering for all in-house plugins + guard (re-targeted to main)#267
Merged
Merged
Conversation
A description bullet containing a colon followed by a space is parsed by YAML as a mapping, which makes ansible-doc abort with 'expected str instance, AnsibleMapping found'. Rephrase the offending bullets in the nextcloud_occ_app_config / nextcloud_occ_system_config modules and the alert_contacts / mwindows / monitors option docs of the uptimerobot_monitor / uptimerobot_psp modules. Add tests/unit/test_plugin_docs.py, which parses every in-house plugin's DOCUMENTATION/RETURN and asserts each description is a string or list of strings, so this class of error fails at unit-test time instead of only at render time. Vendored plugins are out of scope (the ipa* modules also fail ansible-doc, but because their ansible-freeipa doc_fragment is not installed, which is unrelated).
ebuerki-lf
pushed a commit
that referenced
this pull request
May 26, 2026
#267) A description bullet containing a colon followed by a space is parsed by YAML as a mapping, which makes ansible-doc abort with 'expected str instance, AnsibleMapping found'. Rephrase the offending bullets in the nextcloud_occ_app_config / nextcloud_occ_system_config modules and the alert_contacts / mwindows / monitors option docs of the uptimerobot_monitor / uptimerobot_psp modules. Add tests/unit/test_plugin_docs.py, which parses every in-house plugin's DOCUMENTATION/RETURN and asserts each description is a string or list of strings, so this class of error fails at unit-test time instead of only at render time. Vendored plugins are out of scope (the ipa* modules also fail ansible-doc, but because their ansible-freeipa doc_fragment is not installed, which is unrelated).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Re-targets PR #266 to
main. #266 was accidentally based on therefactor/plugins-bitwardenfeature branch and merged there instead of intomain, so its changes never reachedmain. This re-applies the same commit on top of currentmain.The bug
In a
descriptionlist, a bullet with a colon followed by a space is parsed by YAML as a mapping, soansible-docaborts withexpected str instance, AnsibleMapping found. Fixed in:nextcloud_occ_app_config,nextcloud_occ_system_config(top-level description)uptimerobot_monitor(thealert_contactsandmwindowsoption docs)uptimerobot_psp(themonitorsoption doc)The guard
tests/unit/test_plugin_docs.pyparses every in-house plugin'sDOCUMENTATION/RETURNand asserts eachdescriptionis a string or list of strings, so this class of error fails at unit-test time. Vendored plugins (ipa*,lvm_pv) are out of scope.Validation
ansible-docrenders every in-house filter/lookup/module; only the 8 vendoredipa*modules still fail (their ansible-freeipa doc_fragment is not installed, unrelated).