Fix YAML syntax, adjust more code block languages #2408
Conversation
felixfontein
added
the
backport-2.18
felixfontein
temporarily deployed
to
github-bot
GitHub Actions
Inactive
There was a problem hiding this comment.
Thanks very much for this @felixfontein This is great attention to detail and definitely improves the overall quality of the docs. It's much appreciated.
I've left one follow on comment about the console lexer but don't think it's worth getting hung up on. Cheers.
| @@ -361,7 +361,7 @@ and type in the vault password for ``my_user``. | |||
|
|
|||
| The :option:`--vault-id <ansible-playbook --vault-id>` flag allows different vault passwords for different users or different levels of access. The output includes the username ``my_user`` from your ``ansible-vault`` command and uses the YAML syntax ``key: value``: | |||
|
|
|||
| .. code-block:: yaml | |||
| .. code-block:: text | |||
There was a problem hiding this comment.
| .. code-block:: text | |
| .. code-block:: console |
There was a problem hiding this comment.
Hmm. I thought this might be console but now I'm not so sure looking at some of the changes you have below. Given this represents sample output console would make sense, wouldn't it?
There was a problem hiding this comment.
@felixfontein The code-blocks preceding this one are console. Looking at it again, I still think there is a case for console over text. Looking at the pygment docs for the lexer: https://pygments.org/docs/lexers/#pygments.lexers.shell.BashSessionLexer
This code block, while not showing a direct command like the previous ansible-vault examples, is intended to show the output of the --vault-id flag and is in the context of a shell session.
I'm probably being waaaay too pedantic about it though. I don't feel super strongly but am not convinced text is better than console.
There was a problem hiding this comment.
I think console only really makes sense if there's also a prompt involved. The lexer is for formatting prompts, commands, and output differently. Here you can just see program output.
There was a problem hiding this comment.
TBH some of the other ones I've tagged as 'console' likely aren't really console either.
I'm going to keep this one and the others as-is for now, maybe at some point someone has to take a closer look at all these at once. At least now all code blocks are tagged with a language, so they're easier to find :)
Backport to stable-2.18: 💚 backport PR created✅ Backport PR branch: Backported as #2419 🤖 @patchback |
|
@oraNod thanks for reviewing! |
* Fix broken YAML, or adjust code block type. * Normalize code block type. (cherry picked from commit d8c36a0)
* Fix broken YAML, or adjust code block type. * Normalize code block type. (cherry picked from commit d8c36a0) Co-authored-by: Felix Fontein <[email protected]>
* Fix broken YAML, or adjust code block type. * Normalize code block type.
I went through the problems mentioned by #2385 after #2382 got merged.
Quite a few places were things like
...in YAML to indicate "some more content here". I usually replaced it by# ....Another large set (especially in the filters documentation) was something that was a Jinja template, but not really YAML. I usually tagged them as
jinjainstead. Everything that is taggedyaml+jinjashould be syntactially valid YAML. That also means I had to change back #2382 (comment) since this Jinja template cannot be made valid YAML, due to the value fordependencies, which must be a dictionary, and cannot be (in Ansible-style) a YAML string that evaluates to a dictionary.