validate manpages target

Signed-off-by: CrazyMax <[email protected]>

.dockerignore

@@ -2,6 +2,8 @@
 /cli/winresources/versioninfo.json
 /cli/winresources/*.syso
 /man/man*/
+/man/vendor/
+/man/go.sum
 /docs/yaml/
 /docs/vendor/
 /docs/go.sum

.github/workflows/validate.yml

@@ -40,6 +40,7 @@ jobs:
       matrix:
         target:
           - yamldocs # ensure yamldocs target runs fine
+          - manpages # ensure manpages target runs fine
     steps:
       -
         name: Checkout
@@ -48,5 +49,6 @@ jobs:
           fetch-depth: 0
       -
         name: Run
+        shell: 'script --return --quiet --command "bash {0}"'
         run: |
           make -f docker.Makefile ${{ matrix.target }}

.gitignore

@@ -10,9 +10,6 @@ Thumbs.db
 /build/
 /cli/winresources/versioninfo.json
 /cli/winresources/*.syso
-/man/man1/
-/man/man5/
-/man/man8/
 profile.out
 
 # top-level go.mod is not meant to be checked in

Makefile

@@ -11,7 +11,7 @@ _:=$(shell ./scripts/warn-outside-container $(MAKECMDGOALS))
 
 .PHONY: clean
 clean: ## remove build artifacts
-	rm -rf ./build/* cli/winresources/rsrc_* ./man/man[1-9] docs/yaml
+	rm -rf ./build/* man/man[1-9] docs/yaml
 
 .PHONY: test
 test: test-unit ## run tests

man/.gitignore

@@ -0,0 +1,3 @@
+/vendor
+/man*
+/go.sum

man/README.md

@@ -12,4 +12,6 @@ Cobra command or amend the Markdown files for legacy pages.
 
 From within the project root directory run:
 
-    make manpages
+```shell
+$ make -f docker.Makefile manpages
+```

man/generate.go

@@ -1,3 +1,7 @@
+// This file is intended for use with "go run"; it isn't really part of the package.
+
+// +build manpages
+
 package main
 
 import (
@@ -18,6 +22,8 @@ import (
 const descriptionSourcePath = "man/src/"
 
 func generateManPages(opts *options) error {
+	log.SetFlags(0)
+
 	header := &doc.GenManHeader{
 		Title:   "DOCKER",
 		Section: "1",
@@ -73,6 +79,7 @@ func loadLongDescription(cmd *cobra.Command, path string) error {
 			continue
 		}
 
+		log.Printf("INFO: %s found\n", fullpath)
 		content, err := os.ReadFile(fullpath)
 		if err != nil {
 			return err

man/go.mod

@@ -0,0 +1,15 @@
+module github.com/docker/cli/man
+
+// dummy go.mod to avoid dealing with dependencies specific
+// to manpages generation and not really part of the project.
+
+go 1.16
+
+//require (
+//	github.com/docker/cli v0.0.0+incompatible
+//	github.com/cpuguy83/go-md2man/v2 v2.0.1
+//	github.com/spf13/cobra v1.2.1
+//	github.com/spf13/pflag v1.0.5
+//)
+//
+//replace github.com/docker/cli v0.0.0+incompatible => ../

man/tools.go

@@ -0,0 +1,10 @@
+// +build tools
+
+package main
+
+import (
+	_ "github.com/cpuguy83/go-md2man/v2"
+	_ "github.com/spf13/cobra"
+	_ "github.com/spf13/cobra/doc"
+	_ "github.com/spf13/pflag"
+)

scripts/docs/generate-man.sh

@@ -1,17 +1,50 @@
 #!/usr/bin/env bash
-# Generate man pages for docker/cli
-set -eu -o pipefail
 
-mkdir -p ./man/man1
+set -eu
 
-if ! command -v go-md2man &> /dev/null; then
-	# yay, go install creates a binary named "v2" ¯\_(ツ)_/¯
-	go build -o "/go/bin/go-md2man" ./vendor/github.com/cpuguy83/go-md2man/v2
-fi
+: "${MD2MAN_VERSION=v2.0.1}"
 
-# Generate man pages from cobra commands
-go build -o /tmp/gen-manpages github.com/docker/cli/man
-/tmp/gen-manpages --root "$(pwd)" --target "$(pwd)/man/man1"
+export GO111MODULE=auto
 
-# Generate legacy pages from markdown
-./man/md2man-all.sh -q
+function clean {
+  rm -rf "$buildir"
+}
+
+buildir=$(mktemp -d -t docker-cli-docsgen.XXXXXXXXXX)
+trap clean EXIT
+
+(
+  set -x
+  cp -r . "$buildir/"
+  cd "$buildir"
+  # init dummy go.mod
+  ./scripts/vendor init
+  # install go-md2man and copy man/tools.go in root folder
+  # to be able to fetch the required dependencies
+  go mod edit -modfile=vendor.mod -require=github.com/cpuguy83/go-md2man/v2@${MD2MAN_VERSION}
+  cp man/tools.go .
+  # update vendor
+  ./scripts/vendor update
+  # build gen-manpages
+  go build -mod=vendor -modfile=vendor.mod -tags manpages -o /tmp/gen-manpages ./man/generate.go
+  # build go-md2man
+  go build -mod=vendor -modfile=vendor.mod -o /tmp/go-md2man ./vendor/github.com/cpuguy83/go-md2man/v2
+)
+
+mkdir -p man/man1
+(set -x ; /tmp/gen-manpages --root "." --target "$(pwd)/man/man1")
+
+(
+  cd man
+  for FILE in *.md; do
+    base="$(basename "$FILE")"
+    name="${base%.md}"
+    num="${name##*.}"
+    if [ -z "$num" ] || [ "$name" = "$num" ]; then
+      # skip files that aren't of the format xxxx.N.md (like README.md)
+      continue
+    fi
+    mkdir -p "./man${num}"
+    (set -x ; /tmp/go-md2man -in "$FILE" -out "./man${num}/${name}")
+  done
+)

vendor.mod

@@ -10,7 +10,6 @@ require (
 	github.com/Microsoft/go-winio v0.4.19 // indirect
 	github.com/containerd/containerd v1.5.5
 	github.com/coreos/etcd v3.3.25+incompatible // indirect
-	github.com/cpuguy83/go-md2man/v2 v2.0.1
 	github.com/creack/pty v1.1.11
 	github.com/docker/distribution v2.7.1+incompatible
 	github.com/docker/docker v20.10.7+incompatible

vendor.sum

@@ -193,8 +193,6 @@ github.com/coreos/pkg v0.0.0-20160727233714-3ac0863d7acf/go.mod h1:E3G3o1h8I7cfc
 github.com/coreos/pkg v0.0.0-20180928190104-399ea9e2e55f/go.mod h1:E3G3o1h8I7cfcXa63jLwjI0eiQQMgzzUDFVpN/nH/eA=
 github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
 github.com/cpuguy83/go-md2man/v2 v2.0.0/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
-github.com/cpuguy83/go-md2man/v2 v2.0.1 h1:r/myEWzV9lfsM1tFLgDyu0atFtJ1fXn261LKYj/3DxU=
-github.com/cpuguy83/go-md2man/v2 v2.0.1/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/creack/pty v1.1.7/go.mod h1:lj5s0c3V2DBrqTV7llrYr5NG6My20zk30Fl46Y7DoTY=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/creack/pty v1.1.11 h1:07n33Z8lZxZ2qwegKbObQohDhXDQxiMMz1NOUGYlesw=
@@ -555,8 +553,6 @@ github.com/prometheus/procfs v0.0.11/go.mod h1:lV6e/gmhEcM9IjHGsFOCxxuZ+z1YqCvr4
 github.com/rogpeppe/fastuuid v0.0.0-20150106093220-6724a57986af/go.mod h1:XWv6SoW27p1b0cqNHllgS5HIMJraePCO15w5zCzIWYg=
 github.com/rs/xid v1.2.1/go.mod h1:+uKXf+4Djp6Md1KODXJxgGQPKngRmWyn10oCKFzNHOQ=
 github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
-github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
-github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/ryanuber/columnize v0.0.0-20160712163229-9b3edd62028f/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts=
 github.com/safchain/ethtool v0.0.0-20190326074333-42ed695e3de8/go.mod h1:Z0q5wiBQGYcxhMZ6gUqHn6pYNLypFAvaL3UvgZLR0U4=
 github.com/satori/go.uuid v1.2.0/go.mod h1:dA0hQrYB0VpLJoorglMZABFdXlWrHn1NEOzdhQKdks0=