Man support #14

crazy-max · 2021-11-10T09:56:42Z

Add man page support with import of man/generate.go with history from docker/cli.

Use the generate.sh script instead of md2man directly. Update Dockerfile for generating man pages. Signed-off-by: Daniel Nephin <dnephin@docker.com>

Also consolidate the leftover packages under cli. Remove pkg/mflag. Make manpage generation work with new cobra layout. Remove remaining mflag and fix tests after rebase with master. Signed-off-by: Daniel Nephin <dnephin@docker.com>

Using gomvpkg -from github.com/docker/docker/api/client -to github.com/docker/docker/cli/command -vcs_mv_cmd 'git mv {{.Src}} {{.Dst}}' Signed-off-by: Daniel Nephin <dnephin@docker.com>

Signed-off-by: Daniel Nephin <dnephin@docker.com>

Signed-off-by: Kenfe-Mickael Laventure <mickael.laventure@gmail.com>

Signed-off-by: Daniel Nephin <dnephin@docker.com>

Remove the global variable used. Allows easier unit testing. Signed-off-by: Vincent Demeester <vincent@sbr.pm>

Refactor content_trust cli/flags handling

Previously our man pages included the current time each time they were generated. This causes an issue for reproducible builds, since each re-build of a package that includes the man pages will have different times listed in the man pages. To fix this, add support for SOURCE_DATE_EPOCH (which is a standardised packaging environment variable, designed to be used specifically for this purpose[1]). spf13/cobra doesn't support this natively yet (though I will push a patch for that as well), but it's simpler to fix it directly in docker/cli. [1]: https://reproducible-builds.org/specs/source-date-epoch/ Signed-off-by: Aleksa Sarai <asarai@suse.de>

… this removes a whole lot of dependencies from people depending on docker/cli… Signed-off-by: Vincent Demeester <vincent@sbr.pm>

man: obey SOURCE_DATE_EPOCH when generating man pages

Signed-off-by: Silvin Lubecki <silvin.lubecki@docker.com>

…truction Introduce functional arguments to NewDockerCli for a more stable API.

This was set in our manually written markdowns, but not in the man pages generated through Cobra. Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

man-pages: fix missing manual title in heading

codecov-commenter · 2021-11-10T10:23:08Z

Codecov Report

Attention: 27 lines in your changes are missing coverage. Please review.

Comparison is base (e1a3957) 67.36% compared to head (bce3e1e) 70.58%.
Report is 10 commits behind head on main.

Files	Patch %	Lines
clidocstool.go	54.54%	13 Missing and 7 partials ⚠️
clidocstool_man.go	75.00%	3 Missing and 3 partials ⚠️
clidocstool_yaml.go	0.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #14      +/-   ##
==========================================
+ Coverage   67.36%   70.58%   +3.22%     
==========================================
  Files           4        5       +1     
  Lines         576      459     -117     
==========================================
- Hits          388      324      -64     
+ Misses        132       77      -55     
- Partials       56       58       +2

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

thaJeztah · 2021-11-12T10:36:53Z

example/main.go

@@ -59,6 +60,12 @@ func gen(opts *options) error {
 		SourceDir: opts.source,
 		TargetDir: opts.target,
 		Plugin:    true,
+		ManHeader: &doc.GenManHeader{
+			Title:   "BUILDX",
+			Section: "1",


Wondering if we will have cases where not all man-pages must be in the same section https://man7.org/linux/man-pages/man7/man-pages.7.html

e.g. for the cli, we also currently have Dockerfile (5) and dockerd (8). I think in most/all cases a binary would only be in a single section, it's possible that, e.g. a man page describing things like --config could also be in section 5 ("config")

Yes indeed we should take care of it. Will make some changes related to that.

thaJeztah · 2021-11-12T10:40:56Z

clidocstool.go

+func (c *Client) loadLongDescription(parentCmd *cobra.Command, generator string) error {
+	for _, cmd := range parentCmd.Commands() {
+		if cmd.HasSubCommands() {
+			if err := c.loadLongDescription(cmd, generator); err != nil {


Is the intent to use the same markdown files for man pages and online docs?

I know we had some discussions about that in the past, and while this would be "great!", it can be somewhat difficult (and I wasn't able to come up with a one-size-fits-all solution). Conventions in man pages can be quite different from conventions in online docs. For example, the online docs would refer to another command using something like "for details on other command, refer to the <link>other command reference documentation</link>", whereas in a man page it would be "see other-command(1)".

For the cli, that lead us to maintain two separate sets of markdown files (https://github.com/docker/cli/tree/3fb4fb83dfb5db0c0753a8316f21aea54dab32c5/man), but that situation is also kinda horrible, as they're not as well maintained, and often not as up-to-date as the equivalent "online docs" man pages.

Hum yeah it will be hard to be generic with the library. I will think about it and keep you in touch.

I wonder if https://github.com/muesli/mango could solve this issue. I will take a look.

thaJeztah · 2022-02-23T19:53:47Z

😬 looks like this needs a rebase now

thaJeztah · 2022-06-21T07:33:20Z

couple of tests failing, @crazy-max

crazy-max · 2022-12-20T20:11:15Z

@thaJeztah rebased

clidocstool_man_test.go

crazy-max · 2024-02-21T10:49:00Z

example/go.mod

@@ -27,6 +27,7 @@ require (
 	github.com/containerd/continuity v0.2.2 // indirect
 	github.com/containerd/ttrpc v1.1.0 // indirect
 	github.com/containerd/typeurl v1.0.2 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.1 // indirect


Ah let me bump to latest stable 2.0.3

Actually this is an indirect dependency, should we bump cobra @thaJeztah ?

Hm.. good one. Honestly, I think all our CLI's are already on "current" versions of Cobra, so perhaps it's "fine".

OTOH, we don't need "latest" Cobra for this tool, but we DO (likely) want to have the latest go-md2man because we know it has fixes in man-page generating.

So I would be fine starting with updating the dependency here (even if it's indirect); for the "paranoid", you could add a comment, e.g. (// indirect // updated to latest, which has some bug fixes for man-pages)

Perhaps update to v1.6.0 or v1.7.0? v1.6.0 removes the old YAML v2 dependency, and we should update mousetrap to v1.1.0 to remove some legacy code.

Looks like the oldest branch still maintained in docker/cli (23.0) is at v1.6.1, so that could work without disrupting anything; https://github.com/docker/cli/blob/23.0/vendor.mod#L35

thaJeztah · 2024-02-21T10:51:46Z

clidocstool_test.go

+	//tmpdir, err := os.MkdirTemp("", "clidocstool")
+	//require.NoError(t, err)
+	//t.Log(tmpdir)


Looks like some debugging code you forgot to remove

clidocstool_man_test.go

thaJeztah · 2024-02-21T10:57:22Z

fixtures/docker-buildx-stop.1

+.SH DESCRIPTION
+.PP
+Stop builder instance


Do we need a fixture / example with a long description (taken from markdown)? (I think that's implemented in this PR as well, correct?)

Added "attach" and "buildx dial-stdio" that contains long description for testing

thaJeztah · 2024-02-22T12:22:24Z

Rebase time! 😂 ❤️

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

Signed-off-by: CrazyMax <1951866+crazy-max@users.noreply.github.com>

crazy-max · 2024-02-22T12:32:55Z

@thaJeztah Ok should be good now 😇

thaJeztah · 2024-02-29T12:05:31Z

go.mod

@@ -10,7 +10,9 @@ require (
 )

 require (
+	github.com/cpuguy83/go-md2man/v2 v2.0.2 // indirect


Did we still want to push this up a nudge, to v2.0.3? https://github.com/cpuguy83/go-md2man/releases/tag/v2.0.3

I should also check with @cpuguy83 if he's planning to do v2.0.4, as some fixes were merged; cpuguy83/go-md2man@v2.0.3...c2c0656

Can we do this as follow-up? We can still vendor cli-docs-tool main branch in the meantime

Ah, yes, sure; just recalled we were discussing it last week or so 😂

thaJeztah

LGTM

dnephin and others added 17 commits June 2, 2017 00:07

Add a script to generate man pages from cobra commands.

891740e

Use the generate.sh script instead of md2man directly. Update Dockerfile for generating man pages. Signed-off-by: Daniel Nephin <dnephin@docker.com>

Remove old cli framework.

357f26d

Also consolidate the leftover packages under cli. Remove pkg/mflag. Make manpage generation work with new cobra layout. Remove remaining mflag and fix tests after rebase with master. Signed-off-by: Daniel Nephin <dnephin@docker.com>

Move api/client -> cli/command

7b32646

Using gomvpkg -from github.com/docker/docker/api/client -to github.com/docker/docker/cli/command -vcs_mv_cmd 'git mv {{.Src}} {{.Dst}}' Signed-off-by: Daniel Nephin <dnephin@docker.com>

Read long description from a file.

12670c0

Signed-off-by: Daniel Nephin <dnephin@docker.com>

Add example for device-cgroup-rule to man

5f4920e

Signed-off-by: Kenfe-Mickael Laventure <mickael.laventure@gmail.com>

Import completion scripts, docs, and man pages from docker/docker

3ef3474

Add missing dependencies to vendor, and fix generation imports

51917b7

Signed-off-by: Daniel Nephin <dnephin@docker.com>

Disable adding [flags] to UseLine in man pages

524adae

Signed-off-by: Daniel Nephin <dnephin@docker.com>

Refactor content_trust cli/flags handling

9d26ab2

Remove the global variable used. Allows easier unit testing. Signed-off-by: Vincent Demeester <vincent@sbr.pm>

Merge pull request #929 from vdemeester/trust-no-global-var

d55bb8e

Refactor content_trust cli/flags handling

Remove containerizedengine package dependency from docker/cli/command…

98cc7dc

… this removes a whole lot of dependencies from people depending on docker/cli… Signed-off-by: Vincent Demeester <vincent@sbr.pm>

Merge pull request #1306 from cyphar/obey-source_date_epoch

da2b4a4

man: obey SOURCE_DATE_EPOCH when generating man pages

Introduce functional arguments to NewDockerCli for a more stable API.

22ad637

Signed-off-by: Silvin Lubecki <silvin.lubecki@docker.com>

Merge pull request #1633 from silvin-lubecki/refactor-docker-cli-cons…

36c00b3

…truction Introduce functional arguments to NewDockerCli for a more stable API.

man-pages: fix missing manual title in heading

3c98406

This was set in our manually written markdowns, but not in the man pages generated through Cobra. Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

Merge pull request #2801 from thaJeztah/fix_missing_manual_entry

ca0d6b2

man-pages: fix missing manual title in heading

crazy-max force-pushed the man-support branch 5 times, most recently from 07bf100 to 9d3997c Compare November 10, 2021 10:21

thaJeztah reviewed Nov 12, 2021

View reviewed changes

thaJeztah mentioned this pull request Nov 30, 2021

chore: create packages docker/buildx#840

Closed

crazy-max mentioned this pull request Dec 7, 2021

ci: github actions validate workflow docker/cli#3381

Merged

crazy-max force-pushed the man-support branch from 9d3997c to c9aa829 Compare June 18, 2022 09:59

crazy-max force-pushed the man-support branch from c9aa829 to bd3da18 Compare June 21, 2022 07:52

crazy-max force-pushed the man-support branch from bd3da18 to 6d55ae3 Compare June 21, 2022 08:50

crazy-max force-pushed the man-support branch from 6d55ae3 to d8d8f3e Compare December 20, 2022 20:09

crazy-max force-pushed the man-support branch from d8d8f3e to 732dcce Compare February 21, 2024 09:41

crazy-max requested a review from thaJeztah February 21, 2024 09:41

crazy-max commented Feb 21, 2024

View reviewed changes

clidocstool_man_test.go Outdated Show resolved Hide resolved

crazy-max force-pushed the man-support branch from 732dcce to ebc2fad Compare February 21, 2024 09:48

crazy-max commented Feb 21, 2024

View reviewed changes

thaJeztah reviewed Feb 21, 2024

View reviewed changes

crazy-max force-pushed the man-support branch from ebc2fad to bce3e1e Compare February 21, 2024 13:05

crazy-max requested a review from thaJeztah February 21, 2024 13:07

crazy-max mentioned this pull request Feb 22, 2024

vendor: update github.com/spf13/cobra to 1.7.0 #51

Merged

crazy-max and others added 3 commits February 22, 2024 13:27

Import man/generate.go with history from docker/cli

5090452

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

add man support

be388bf

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

test: "attach" and "buildx dial-stdio" cmds for testing

4ecc2f2

Signed-off-by: CrazyMax <1951866+crazy-max@users.noreply.github.com>

crazy-max force-pushed the man-support branch from bce3e1e to 4ecc2f2 Compare February 22, 2024 12:29

thaJeztah reviewed Feb 29, 2024

View reviewed changes

thaJeztah approved these changes Feb 29, 2024

View reviewed changes

thaJeztah merged commit 27c3157 into docker:main Feb 29, 2024
3 checks passed

crazy-max deleted the man-support branch February 29, 2024 12:10

thaJeztah mentioned this pull request Feb 29, 2024

docs: include required tools in source tree docker/cli#4903

Draft

crazy-max mentioned this pull request Mar 1, 2024

vendor: github.com/docker/cli-docs-tool to master docker/buildx#2301

Closed

thaJeztah mentioned this pull request Aug 7, 2024

Move dockerd man page back from docker/cli moby/moby#48298

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Man support #14

Man support #14

crazy-max commented Nov 10, 2021

codecov-commenter commented Nov 10, 2021 •

edited

Loading

thaJeztah Nov 12, 2021

crazy-max Nov 16, 2021

thaJeztah Nov 12, 2021

crazy-max Nov 16, 2021

crazy-max Jan 18, 2022

thaJeztah commented Feb 23, 2022

thaJeztah commented Jun 21, 2022

crazy-max commented Dec 20, 2022

crazy-max Feb 21, 2024

crazy-max Feb 21, 2024

thaJeztah Feb 22, 2024

thaJeztah Feb 22, 2024

thaJeztah Feb 21, 2024

thaJeztah Feb 21, 2024

crazy-max Feb 21, 2024

thaJeztah commented Feb 22, 2024

crazy-max commented Feb 22, 2024

thaJeztah Feb 29, 2024

crazy-max Feb 29, 2024 •

edited

Loading

thaJeztah Feb 29, 2024

thaJeztah left a comment

Man support #14

Man support #14

Conversation

crazy-max commented Nov 10, 2021

codecov-commenter commented Nov 10, 2021 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thaJeztah commented Feb 23, 2022

thaJeztah commented Jun 21, 2022

crazy-max commented Dec 20, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thaJeztah commented Feb 22, 2024

crazy-max commented Feb 22, 2024

Choose a reason for hiding this comment

crazy-max Feb 29, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thaJeztah left a comment

Choose a reason for hiding this comment

codecov-commenter commented Nov 10, 2021 •

edited

Loading

crazy-max Feb 29, 2024 •

edited

Loading