@@ -126,6 +126,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)

@@ -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,

 	}

@@ -131,9 +132,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}}

@@ -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}"

@@ -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

@@ -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

-	man/md2man-all.sh -q

+	# Include man pages

+	man/generate.sh

 	manRoot="$DIR/usr/share/man"

 	mkdir -p "$manRoot"

 	for manDir in man/man?; do

@@ -1,7 +1,20 @@

-FROM golang:1.6.3

-RUN mkdir -p /go/src/github.com/cpuguy83

-RUN mkdir -p /go/src/github.com/cpuguy83 \

-    && 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 \

-    && go get -v ./...

-CMD ["/go/bin/go-md2man", "--help"]

+FROM    golang:1.6.3-alpine

+

+RUN     apk add -U git bash curl gcc musl-dev

+

+RUN     export GLIDE=0.10.2; \

+        export SRC=https://github.com/Masterminds/glide/releases/download/; \

+        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"]

@@ -1,33 +1,15 @@

 Docker Documentation

 ====================

-This directory contains the Docker user manual in the Markdown format.

-Do *not* edit the man pages in the man1 directory. Instead, amend the

-Markdown (*.md) files.

+This directory contains scripts for generating the man pages. Many of the man

+pages are generated directly from the `spf13/cobra` `Command` definition. Some

+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

-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.

+## Generate the mange pages

-## Building the md2man image

+From within the project root directory run:

-There is a `Dockerfile` provided in the `/man` directory of your

-'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/).

+    make manpages

new file mode 100644

@@ -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())

+	}

+}

new file mode 100755

@@ -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

new file mode 100644

@@ -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: []

new file mode 100644

@@ -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