make manpages will output Yaml files within the yaml/ directory

man pages are troff formatted, so it's a little strange that make manpages would output YAML. Is this a precursor format that later gets converted to man pages?

@aaronlehmann bleh.. it looks like I missed some the changes to the repo structure.
You're correct, this generates more than just manpages as I piggy backed on the function used in manpage.

The yaml output is used to build the docs.docker.com pages, but will never be stored within docker/docker - The idea is that our docs reflect 100% the cli code logic without having developers update the yaml files separately.

This should be built in CI, otherwise no idea when it breaks.

@justincormack that's the idea - the CI piece still needs to be added.

design is ok for me

Can we make sure that the files in man/src are brought in sync with the docs/reference/commandline documentation? I think there may be information present in the docs/ files that is not present in the man pages (and vice-versa).

Also, what's the approach to link from the reference docs to other parts of the documentation? For example, https://github.com/docker/docker/blob/master/docs/reference/commandline/run.md refers to various other parts of the docs, but the https://github.com/docker/docker/blob/master/man/docker-run.1.md man page (which is not in man/src) does not have those links (as man pages usually link to other man-pages, but not to online docs).

Our man pages have historically been a lot less complete than the online docs, so we should look carefully when moving to using those as documentation, as they are far from complete.

Do man-pages support tables? (see https://github.com/docker/docker/blob/master/docs/reference/commandline/run.md#restart-policies---restart)

Ping @FrenchBen let us know if you need help with this.

After conversation with @tiborvass and @thaJeztah the following will happen:

1. docs/reference/commandline will be the new source of truth for the extended descriptions
2. The above MD will need to partially remove the current CLI output within the markdown
3. docs/reference/commandline will need to be update to have all canonical commands and their aliases

@FrenchBen there are some compile errors due to unvendored dependency.

We need to check license compatibility as well (https://github.com/jteeuwen/go-bindata);

This work is subject to the CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
license. Its contents can be found at:
http://creativecommons.org/publicdomain/zero/1.0

Thanks for checking @justincormack

Right now, the yaml/Dockerfile doesn't work. It needs to install mercurial and also there is some problem with where the generate.sh gets put vs the WORKDIR. I tried a few permutations but I couldn't figure it out.

Also, #30804 is now in master. It standardizes the format of the CLI references so that they will be easier for this PR to consume:

The long description should be grabbed from between ## Description to ## Examples. If there is no ## Description then there is no long description.

The examples should be grabbed from between ## Examples to the next H2-level heading, or to the end of the file, whichever comes first. If there is no ## Examples there are no examples.

Both of these should be grabbed as a string of Markdown.

ping @FrenchBen can you take a look at @mstanleyjones's comments ?

@FrenchBen told me during lunch that he was working on this 😄

Latest output LGTM. Note that we need to be somewhat rigorous about the formatting of the CLI reference files. If there is a Description or Examples section, it needs to be a H2 section. And if there are any complicated tables with block level elements they need to be HTML tables. There may be more "gotchas" in future.

Ping @estesp @duglin not sure what powerpc did there: https://jenkins.dockerproject.org/job/Docker-PRs-powerpc/361/console

@tiborvass seems like the power issue was a flake, seems to have vanished.