cmd: set double quotes as code delimiter

[crazy-max]

follow-up docker/docs#16093 (comment)

- What I did

Set " as code delimiter for flags usage output to fix issue with docs generation.

Also generates markdown in reference docs to be aligned as it seems we drifted a bit. Frontmatter section in md files doesn't seem to be used anymore so remove it as well.

And I found out that #2936 and #2024 break markdown tables (see last 2 commits).

In follow-up we should also validate docs like it's done in buildx: https://github.com/docker/buildx/blob/88852e2330a200d495342e01783a922a5328d55c/hack/dockerfiles/docs.Dockerfile#L30-L43

- How I did it

- How to verify it

- Description for the changelog

- A picture of a cute animal (not mandatory but encouraged)

[codecov-commenter]

Codecov Report

Merging #3924 (b7d9555) into master (99023cb) will decrease coverage by 0.00%.
The diff coverage is 73.21%.

❗ Current head b7d9555 differs from pull request most recent head 8fbaac0. Consider uploading reports for the commit 8fbaac0 to get more accurate results

Additional details and impacted files

@@ Coverage Diff @@## master #3924 +/- ##
==========================================
- Coverage 59.20% 59.20% -0.01% 
==========================================
Files 287 287 Lines 24687 24690 +3 ==========================================
Hits 14617 14617 - Misses 9186 9189 +3 
Partials 884 884 

[crazy-max]

@thaJeztah I wonder if https://github.com/docker/cli/blob/master/docs/reference/commandline/dockerd.md should not be in moby repo instead?

[thaJeztah]

I wonder if https://github.com/docker/cli/blob/master/docs/reference/commandline/dockerd.md should not be in moby repo instead?

Yeah, there was a bit of a debate at the time about that. I suggested it should be in the moby repo, but ISTR there were some reasons at the time to move it as well (but it may have been "it's easier to move all files").

We should look at moving it back, but ideally preserving history (might be fun as it will contain history from "before" it was moved and "after", and possibly because of the move; same history twice 😅 😓).

[thaJeztah]

Thanks! Overall looking great! Left two comments (and opened a PR 😄 )

[thaJeztah]

I'm slightly on the fence on these (but admitted: we weren't very consistent); slightly wondering what's clearer on intent;

• "foo"|"bar" either "foo" (string) or "bar" (string)
• "foo|bar" a string of either foo or bar
• some other notation? ("foo", "bar", or "baz") ?
• extended notation for all of these (multiple lines; short explanation for each option)

/cc @dvdksn@vvoland@usha-mandya

[dvdksn]

in the build docs we've used comma-separated notation, and the options wrapped in code spans. My subjective opinion is that comma is more readable than pipes, but this is probably debatable.

[vvoland]

IMO single quotes containing all options are confusing ("foo|bar").
Personally I find commas clearer than pipes when only one value can be given at once, so 3rd option looks good for me:

flags.StringVar(&options.role, flagRole, "", `Role of the node ("worker" or "manager")`)
flags.StringVar(&options.availability, flagAvailability, "", `Availability of the node ("active", "pause" or "drain")`)

[thaJeztah]

Looks like an e2e test needs updating;

=== FAIL: e2e/stack TestStackDeployHelp (0.05s)
help_test.go:13: assertion failed: --- expected
+++ actual
@@ -12,6 +12,6 @@
······--prune··················Prune·services·that·are·no·longer·referenced
······--resolve-image·string···Query·the·registry·to·resolve·image·digest
-·······························and·supported·platforms
-·······························("always",·"changed",·"never")·(default·"always")
+·······························and·supported·platforms·("always",
+·······························"changed",·"never")·(default·"always")
······--with-registry-auth·····Send·registry·authentication·details·to
·······························Swarm·agents
You can run 'go test . -update' to automatically update testdata/stack-deploy-help.golden to the new expected value.'

[thaJeztah]

LGTM!

I swapped the last two commits, so that we have the option of cherry-picking the anchor quote fixes

[thaJeztah]

Arf, and of course then it wants the DCO to be fixed; let me do so