Docs RFC: use `<code>` for default values, sample values, and choice values?

[felixfontein]

Summary

Right now, while values in the description that are (correctly) formtated with C(...) have code / teletype formatting, other auto-generated values such as choice list entries, defaults, and samples, are formatted as regular text (only with different colors). We want to change that.

See ansible-community/antsibull-docs#38 (comment) - implementation is in ansible-community/antsibull-docs#42.

You can see some live examples here:

• https://ansible.fontein.de/collections/community/crypto/acme_account_info_module.html#parameter-request_timeout
• https://ansible.fontein.de/collections/community/crypto/x509_certificate_info_module.html#return-public_key_fingerprints
• https://ansible.fontein.de/collections/ansible/builtin/combine_filter.html#parameter-list_merge

Compare these to the corresponding parts from the devel docs:

• https://docs.ansible.com/ansible/devel//collections/community/crypto/acme_account_info_module.html#parameter-request_timeout
• https://docs.ansible.com/ansible/devel//collections/community/crypto/x509_certificate_info_module.html#return-public_key_fingerprints
• https://docs.ansible.com/ansible/devel/collections/ansible/builtin/combine_filter.html#parameter-list_merge

What are your opinions on this change? If nobody complains until after this week's community meeting (Wednesday 18:00-19:00 UTC), this change will get merged (and should eventually end up in the devel docs).

[russoz]

Looks good to me :-)

For the (pedantic) record:

... are formatted as regular text (only with different colors).

That is not entirely correct: the "regular" text comes with typographic quotes, cumbersome for copying/pasting.

There's too many of them: https://en.wikipedia.org/wiki/Quotation_mark

[russoz]

Any chance we can take the opportunity and to something about: https://ansible.fontein.de/collections/community/crypto/acme_account_info_module.html#return-account/public_account_key

"{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4\",\"y\":\"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM\"}"

Given that we do not put quotes around lists in that output, why do we do that with dicts?

[felixfontein]

@russoz because the return type here is a string and not a dictionary. (https://github.com/ansible-collections/community.crypto/blob/main/plugins/modules/acme_account_info.py#L122)

[russoz]

Should it be a string?

[felixfontein]

It's a public key, so I would say yes. But that's totally off-topic to this discussion. :)

[briantist]

Well you already know what I think ;)
(I much prefer the code style, thanks for your work on this!)

[felixfontein]

Thanks everyone! I'm going to merge that PR now, since nobody objected to the style either here, in the antsibull-docs repo, or in the docs or community meetings.

[Andersson007]

Looks much better when using <code>, definitely +1, thanks everyone!