Skip to content
This repository has been archived by the owner on May 14, 2024. It is now read-only.

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

Closed
felixfontein opened this issue Oct 3, 2022 · 8 comments

Comments

@felixfontein
Copy link
Contributor

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:

Compare these to the corresponding parts from the devel docs:

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
Copy link
Contributor

russoz commented Oct 3, 2022

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
Copy link
Contributor

russoz commented Oct 3, 2022

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
Copy link
Contributor Author

@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
Copy link
Contributor

russoz commented Oct 4, 2022

Should it be a string?

@felixfontein
Copy link
Contributor Author

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

@briantist
Copy link

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

@felixfontein
Copy link
Contributor Author

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
Copy link
Contributor

Andersson007 commented Oct 6, 2022

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

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

4 participants