Add a script to generate man pages from cobra commands.

Use the generate.sh script instead of md2man directly.
Update Dockerfile for generating man pages.

Signed-off-by: Daniel Nephin <dnephin@docker.com>
(cherry picked from commit 00a8a40398)
Signed-off-by: Tibor Vass <tibor@docker.com>

Makefile

@@ -115,6 +115,12 @@ test-unit: build ## run the unit tests
 validate: build ## validate DCO, Seccomp profile generation, gofmt,\n./pkg/ isolation, golint, tests, tomls, go vet and vendor 
 	$(DOCKER_RUN_DOCKER) hack/make.sh validate-dco validate-default-seccomp validate-gofmt validate-pkg validate-lint validate-test validate-toml validate-vet validate-vendor
 
+manpages: ## Generate man pages from go source and markdown
+	docker build -t docker-manpage-dev -f man/Dockerfile .
+	docker run \
+		-v $(PWD):/go/src/github.com/docker/docker/ \
+		docker-manpage-dev
+
 help: ## this help
 	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {sub("\\\\n",sprintf("\n%22c"," "), $$2);printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
 

cli/cobraadaptor/adaptor.go

@@ -33,6 +33,7 @@ func NewCobraAdaptor(clientFlags *cliflags.ClientFlags) CobraAdaptor {
 
 	var rootCmd = &cobra.Command{
 		Use:           "docker [OPTIONS]",
+		Short:         "A self-sufficient runtime for containers",
 		SilenceUsage:  true,
 		SilenceErrors: true,
 	}
@@ -129,9 +130,15 @@ func (c CobraAdaptor) Command(name string) func(...string) error {
 	return nil
 }
 
+// GetRootCommand returns the root command. Required to generate the man pages
+// and reference docs from a script outside this package.
+func (c CobraAdaptor) GetRootCommand() *cobra.Command {
+	return c.rootCmd
+}
+
 var usageTemplate = `Usage:	{{if not .HasSubCommands}}{{.UseLine}}{{end}}{{if .HasSubCommands}}{{ .CommandPath}} COMMAND{{end}}
 
-{{with or .Long .Short }}{{. | trim}}{{end}}{{if gt .Aliases 0}}
+{{ .Short | trim }}{{if gt .Aliases 0}}
 
 Aliases:
   {{.NameAndAliases}}{{end}}{{if .HasExample}}

hack/make/build-deb

@@ -35,7 +35,7 @@ set -e
 	debDate="$(date --rfc-2822)"
 
 	# if go-md2man is available, pre-generate the man pages
-	./man/md2man-all.sh -q || true
+	./man/generate.sh || true
 	# TODO decide if it's worth getting go-md2man in _each_ builder environment to avoid this
 
 	builderDir="contrib/builder/deb/${PACKAGE_ARCH}"

hack/make/build-rpm

@@ -51,7 +51,7 @@ set -e
 	rpmDate="$(date +'%a %b %d %Y')"
 
 	# if go-md2man is available, pre-generate the man pages
-	./man/md2man-all.sh -q || true
+	./man/generate.sh || true
 	# TODO decide if it's worth getting go-md2man in _each_ builder environment to avoid this
 
 	# Convert the CHANGELOG.md file into RPM changelog format

hack/make/ubuntu

@@ -59,8 +59,8 @@ bundle_ubuntu() {
 	mkdir -p "$DIR/etc/fish/completions"
 	cp contrib/completion/fish/docker.fish "$DIR/etc/fish/completions/"
 
-	# Include contributed man pages
+	# Include man pages
-	man/md2man-all.sh -q
+	man/generate.sh
 	manRoot="$DIR/usr/share/man"
 	mkdir -p "$manRoot"
 	for manDir in man/man?; do

man/Dockerfile

@@ -1,7 +1,20 @@
-FROM golang:1.6.3
+FROM    golang:1.6.3-alpine
-RUN mkdir -p /go/src/github.com/cpuguy83
+
-RUN mkdir -p /go/src/github.com/cpuguy83 \
+RUN     apk add -U git bash curl gcc musl-dev
-    && git clone -b v1.0.5 https://github.com/cpuguy83/go-md2man.git /go/src/github.com/cpuguy83/go-md2man \
+
-    && cd /go/src/github.com/cpuguy83/go-md2man \
+RUN     export GLIDE=0.10.2; \
-    && go get -v ./...
+        export SRC=https://github.com/Masterminds/glide/releases/download/; \
-CMD ["/go/bin/go-md2man", "--help"]
+        curl -sL ${SRC}/${GLIDE}/glide-${GLIDE}-linux-amd64.tar.gz | \
+        tar -xz linux-amd64/glide && \
+        mv linux-amd64/glide /usr/bin/glide && \
+        chmod +x /usr/bin/glide
+
+COPY    man/glide.yaml /manvendor/
+COPY    man/glide.lock /manvendor/
+WORKDIR /manvendor/
+RUN     glide install && mv vendor src
+ENV     GOPATH=$GOPATH:/go/src/github.com/docker/docker/vendor:/manvendor
+RUN     go build -o /usr/bin/go-md2man github.com/cpuguy83/go-md2man
+
+WORKDIR /go/src/github.com/docker/docker/
+ENTRYPOINT ["man/generate.sh"]

man/README.md

@@ -1,33 +1,15 @@
 Docker Documentation
 ====================
 
-This directory contains the Docker user manual in the Markdown format.
+This directory contains scripts for generating the man pages. Many of the man
-Do *not* edit the man pages in the man1 directory. Instead, amend the
+pages are generated directly from the `spf13/cobra` `Command` definition. Some
-Markdown (*.md) files.
+legacy pages are still generated from the markdown files in this directory.
+Do *not* edit the man pages in the man1 directory. Instead, update the
+Cobra command or amend the Markdown files for legacy pages.
 
-# Generating man pages from the Markdown files
 
-The recommended approach for generating the man pages is via a Docker
+## Generate the mange pages
-container using the supplied `Dockerfile` to create an image with the correct
-environment. This uses `go-md2man`, a pure Go Markdown to man page generator.
 
-## Building the md2man image
+From within the project root directory run:
 
-There is a `Dockerfile` provided in the `/man` directory of your
+    make manpages
-'docker/docker' fork.
-
-Using this `Dockerfile`, create a Docker image tagged `docker/md2man`:
-
-    docker build -t docker/md2man .
-
-## Utilizing the image
-
-From within the `/man` directory run the following command:
-
-    docker run -v $(pwd):/man -w /man -i docker/md2man ./md2man-all.sh
-    
-The `md2man` Docker container will process the Markdown files and generate
-the man pages inside the `/man/man1` directory of your fork using
-Docker volumes. For more information on Docker volumes see the man page for
-`docker run` and also look at the article [Sharing Directories via Volumes]
-(https://docs.docker.com/use/working_with_volumes/).

man/generate.go

@@ -0,0 +1,39 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/docker/docker/cli/cobraadaptor"
+	cliflags "github.com/docker/docker/cli/flags"
+	"github.com/spf13/cobra/doc"
+)
+
+func generateManPages(path string) error {
+	header := &doc.GenManHeader{
+		Title:   "DOCKER",
+		Section: "1",
+		Source:  "Docker Community",
+	}
+	flags := &cliflags.ClientFlags{
+		Common: cliflags.InitCommonFlags(),
+	}
+	cmd := cobraadaptor.NewCobraAdaptor(flags).GetRootCommand()
+	cmd.DisableAutoGenTag = true
+	return doc.GenManTreeFromOpts(cmd, doc.GenManTreeOptions{
+		Header:           header,
+		Path:             path,
+		CommandSeparator: "-",
+	})
+}
+
+func main() {
+	path := "/tmp"
+	if len(os.Args) > 1 {
+		path = os.Args[1]
+	}
+	fmt.Printf("Generating man pages into %s\n", path)
+	if err := generateManPages(path); err != nil {
+		fmt.Fprintf(os.Stderr, "Failed to generate man pages: %s\n", err.Error())
+	}
+}

man/generate.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+#
+# Generate man pages for docker/docker
+#
+
+set -eu
+
+mkdir -p ./man/man1
+
+# Generate man pages from cobra commands
+go build -o /tmp/gen-manpages ./man
+/tmp/gen-manpages ./man/man1
+
+# Generate legacy pages from markdown
+./man/md2man-all.sh -q

man/glide.lock

@@ -0,0 +1,52 @@
+hash: ead3ea293a6143fe41069ebec814bf197d8c43a92cc7666b1f7e21a419b46feb
+updated: 2016-06-20T21:53:35.420817456Z
+imports:
+- name: github.com/BurntSushi/toml
+  version: f0aeabca5a127c4078abb8c8d64298b147264b55
+- name: github.com/cpuguy83/go-md2man
+  version: 2724a9c9051aa62e9cca11304e7dd518e9e41599
+  subpackages:
+  - md2man
+- name: github.com/fsnotify/fsnotify
+  version: 30411dbcefb7a1da7e84f75530ad3abe4011b4f8
+- name: github.com/hashicorp/hcl
+  version: da486364306ed66c218be9b7953e19173447c18b
+  subpackages:
+  - hcl/ast
+  - hcl/parser
+  - hcl/token
+  - json/parser
+  - hcl/scanner
+  - hcl/strconv
+  - json/scanner
+  - json/token
+- name: github.com/inconshreveable/mousetrap
+  version: 76626ae9c91c4f2a10f34cad8ce83ea42c93bb75
+- name: github.com/magiconair/properties
+  version: c265cfa48dda6474e208715ca93e987829f572f8
+- name: github.com/mitchellh/mapstructure
+  version: d2dd0262208475919e1a362f675cfc0e7c10e905
+- name: github.com/russross/blackfriday
+  version: 1d6b8e9301e720b08a8938b8c25c018285885438
+- name: github.com/shurcooL/sanitized_anchor_name
+  version: 10ef21a441db47d8b13ebcc5fd2310f636973c77
+- name: github.com/spf13/cast
+  version: 27b586b42e29bec072fe7379259cc719e1289da6
+- name: github.com/spf13/jwalterweatherman
+  version: 33c24e77fb80341fe7130ee7c594256ff08ccc46
+- name: github.com/spf13/pflag
+  version: 367864438f1b1a3c7db4da06a2f55b144e6784e0
+- name: github.com/spf13/viper
+  version: c1ccc378a054ea8d4e38d8c67f6938d4760b53dd
+- name: golang.org/x/sys
+  version: 62bee037599929a6e9146f29d10dd5208c43507d
+  subpackages:
+  - unix
+- name: gopkg.in/yaml.v2
+  version: a83829b6f1293c91addabc89d0571c246397bbf4
+- name: github.com/spf13/cobra
+  repo: https://github.com/dnephin/cobra
+  subpackages:
+  - doc
+  version: dc45219961f875acff5ee07ed263e5dc19e0c5f1
+devImports: []

man/glide.yaml

@@ -0,0 +1,12 @@
+package: github.com/docker/docker/man
+import:
+- package: github.com/cpuguy83/go-md2man
+  subpackages:
+  - md2man
+- package: github.com/inconshreveable/mousetrap
+- package: github.com/spf13/pflag
+- package: github.com/spf13/viper
+- package: github.com/spf13/cobra
+  repo: https://github.com/dnephin/cobra
+  subpackages:
+  - doc