ansible-collections / ansible-collections/google.cloud

Line breaks in documentation strings give problems

Open
#248 1 comment 0 reactions 0 assignees View on GitHub
stale
Dominant language
Python
Stars
105
Forks
144
Avg merge
5d 10h
Merged PRs (30d)
4

Description

##### SUMMARY
This line doesn't look like it's getting parsed as expected:

https://github.com/ansible-collections/google.cloud/blob/c41f599aee62016fec098baf0363c987e0711b1a/plugins/modules/gcp_pubsub_subscription.py#L208

There's another example or two.

Basically, this isn't a raw string, so python itself isn't going to differentiate between line breaks which are intended to be part of the YAML entry or actual line breaks (this is before any YAML parsing actually happens).

The auto-generator tool should probably sanitize these out.

I've tried to figure out what the effect is with `ansible-doc`, and it kind of weirdly doesn't show this option, so it's not being explicit with the error, but I think there's some YAML error being produced there.

##### ISSUE TYPE
- Bug Report

##### COMPONENT NAME

##### ANSIBLE VERSION
most recent commit, 4944f92b721a3b78c6040fad9273c4d4bc484793

##### CONFIGURATION
defaults

##### OS / ENVIRONMENT
N/A

##### STEPS TO REPRODUCE
use `ansible-doc`, see behavior I mentioned with missing full options from this module

or try to parse module's DOCUMENTATION with yaml

##### EXPECTED RESULTS
valid yaml

##### ACTUAL RESULTS
not valid yaml

Making this a raw string seems to fix it.

Contributor guide

Open the contributing guide

Research direction

Start with plugins/modules/gcp_pubsub_subscription.py at the linked documentation string and reproduce the issue using ansible-doc or by parsing DOCUMENTATION with yaml. Trace how the auto-generator handles line breaks before YAML parsing; done means the module documentation is valid YAML and ansible-doc displays all options.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, yaml
Domain
documentation, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.