Move the command description to a markdown file for man pages by dnephin · Pull Request #26830 · moby/moby

dnephin · 2016-09-22T18:55:57Z

Following up on some concerns from #23825 and #25615.

This changes moves the command "long description" back to a markdown file, so that we can use "`" and so that docs contributors don't have to edit source files.

It still uses the cobra man page generation for the flags and the rest of the structure, but reads the long description from a file.

I've ported over the volume commands, which were using the in-lined description, as well as all the network commands, and a couple random top-level commands. If this looks good I can proceed with the rest as part of #26721

dnephin · 2016-09-22T18:56:11Z

cc @thaJeztah @vdemeester

thaJeztah · 2016-10-17T20:37:17Z

man/docker-top.1.md

Do you know if these "history" lines have any official meaning in man files; iow is it OK to omit them? (just curious)

I believe this is just a header/section like any other. I took a lot at man git, and man top, and neither of them have history sections (at least on arch).

Alright, thanks! I won't miss them (and they are really outdated), so good to get rid of them I think

thaJeztah · 2016-10-17T20:38:13Z

man/src/network/disconnect.md

nit while I'm browsing; should be no space before $

thaJeztah · 2016-10-17T20:43:26Z

I really like this! Wondering if we need the nested directories for sub commands (volumes/ls), and possibly name it partials or so (instead of src), but that's just bike shedding, no big issue.

We could even expand on this in future to re-use this for the reference docs

design LGTM, I'm moving this to code review, but /cc @vdemeester as well

dnephin · 2016-10-17T20:50:41Z

Wondering if we need the nested directories for sub commands

We could use underscore separators instead of directories, but I prefer directories.

possibly name it partials or so (instead of src)

partials to me implies that you could mix them together. It's true that they aren't the complete source. I like src, but if we want to change it, something like descriptions might be more appropriate than partials.

We could even expand on this in future to re-use this for the reference docs

Absolutely. I'm going to start setting that up now as part of #26784 I think

thaJeztah · 2016-10-17T20:56:20Z

Thanks! Yeah, the naming is just bike-shedding, and no strong preference on my side, so 👍

thaJeztah · 2016-10-25T07:33:40Z

ping @vdemeester PTAL

dnephin · 2016-11-04T18:11:47Z

ping, rebased again

thaJeztah · 2016-11-04T23:30:06Z

hmf needs another rebase already

ping @vdemeester, ptal !

FrenchBen · 2016-11-28T23:20:35Z

ping @vdemeester for review - @dnephin this needs another rebase it seems :\

thaJeztah · 2016-12-22T19:35:41Z

@dnephin could you rebase?

dnephin · 2016-12-27T16:30:14Z

I've been rebasing this almost every week for a few months. I can do it again, but it seems kind of pointless unless we're ready to merge this sometime soon.

dnephin · 2016-12-27T16:36:30Z

rebased again

FrenchBen · 2016-12-28T19:37:52Z

Can we please get this merged asap?

vdemeester

LGTM 🐸
@dnephin could you squash your commit though 👼 (actual commit message are pretty much the same for all commits 😓)

Signed-off-by: Daniel Nephin <[email protected]>

dnephin · 2017-01-03T14:34:07Z

Squashed, and build is green

thaJeztah

LGTM

Move the command description to a markdown file for man pages

GordonTheTurtle added the status/0-triage label Sep 22, 2016

justincormack added status/1-design-review and removed status/0-triage labels Sep 24, 2016

dnephin force-pushed the man-desc-in-files branch from 985c4e5 to 1b179b8 Compare October 17, 2016 20:37

thaJeztah reviewed Oct 17, 2016

View reviewed changes

man/src/network/disconnect.md Outdated

Copy link

Member

thaJeztah Oct 17, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit while I'm browsing; should be no space before $

dnephin force-pushed the man-desc-in-files branch from 1b179b8 to dd4c649 Compare October 17, 2016 20:40

thaJeztah added status/2-code-review and removed status/1-design-review labels Oct 17, 2016

dnephin force-pushed the man-desc-in-files branch 2 times, most recently from 631b633 to 50ec08c Compare October 20, 2016 22:45

dnephin force-pushed the man-desc-in-files branch 2 times, most recently from 6d9764c to 667e1e3 Compare November 4, 2016 18:11

dnephin force-pushed the man-desc-in-files branch from 667e1e3 to bae34a2 Compare November 4, 2016 19:51

dnephin force-pushed the man-desc-in-files branch from bae34a2 to c7be038 Compare November 7, 2016 22:55

FrenchBen mentioned this pull request Nov 29, 2016

Initial dump of CLI in yaml docker/docs#737

Merged

dnephin force-pushed the man-desc-in-files branch from c7be038 to 0e06630 Compare November 29, 2016 20:30

dnephin force-pushed the man-desc-in-files branch from 0e06630 to 63a1b40 Compare December 27, 2016 16:36

vdemeester self-assigned this Dec 27, 2016

dnephin added the rebuild/windowsRS1 label Dec 27, 2016

GordonTheTurtle removed the rebuild/windowsRS1 label Dec 27, 2016

vdemeester approved these changes Dec 28, 2016

View reviewed changes

Read long description from a file.

78101b2

Signed-off-by: Daniel Nephin <[email protected]>

dnephin force-pushed the man-desc-in-files branch from 63a1b40 to 78101b2 Compare December 28, 2016 21:09

dnephin added the rebuild/experimental label Dec 29, 2016

GordonTheTurtle removed the rebuild/experimental label Dec 29, 2016

thaJeztah approved these changes Jan 3, 2017

View reviewed changes

thaJeztah merged commit e4223e3 into moby:master Jan 3, 2017

GordonTheTurtle added this to the 1.14.0 milestone Jan 3, 2017

dnephin deleted the man-desc-in-files branch January 4, 2017 15:11

dnephin pushed a commit to dnephin/docker that referenced this pull request Apr 17, 2017

Merge pull request moby#26830 from dnephin/man-desc-in-files

f2cac1b

Move the command description to a markdown file for man pages

thaJeztah mentioned this pull request Jun 12, 2018

Show long help message when defined docker/cli#1098

Merged

Conversation

dnephin commented Sep 22, 2016

Uh oh!

dnephin commented Sep 22, 2016

Uh oh!

thaJeztah Oct 17, 2016

Choose a reason for hiding this comment

Uh oh!

dnephin Oct 17, 2016

Choose a reason for hiding this comment

Uh oh!

thaJeztah Oct 17, 2016

Choose a reason for hiding this comment

Uh oh!

thaJeztah Oct 17, 2016

Choose a reason for hiding this comment

Uh oh!

thaJeztah commented Oct 17, 2016

Uh oh!

dnephin commented Oct 17, 2016

Uh oh!

thaJeztah commented Oct 17, 2016

Uh oh!

thaJeztah commented Oct 25, 2016

Uh oh!

dnephin commented Nov 4, 2016

Uh oh!

thaJeztah commented Nov 4, 2016

Uh oh!

FrenchBen commented Nov 28, 2016

Uh oh!

thaJeztah commented Dec 22, 2016

Uh oh!

dnephin commented Dec 27, 2016

Uh oh!

dnephin commented Dec 27, 2016

Uh oh!

FrenchBen commented Dec 28, 2016

Uh oh!

vdemeester left a comment

Choose a reason for hiding this comment

Uh oh!

dnephin commented Jan 3, 2017

Uh oh!

thaJeztah left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants