From ea0d7e52715b687a3cc70b21287d5447ce90f0d6 Mon Sep 17 00:00:00 2001 From: Daniel Nephin Date: Thu, 9 Jun 2016 11:33:28 -0400 Subject: [PATCH] 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 (cherry picked from commit 00a8a40398263429f99b1a5f0be59048e1c6f38d) Signed-off-by: Tibor Vass --- Makefile | 6 +++++ cli/cobraadaptor/adaptor.go | 9 ++++++- hack/make/build-deb | 2 +- hack/make/build-rpm | 2 +- hack/make/ubuntu | 4 +-- man/Dockerfile | 27 ++++++++++++++----- man/README.md | 34 ++++++------------------ man/generate.go | 39 ++++++++++++++++++++++++++++ man/generate.sh | 15 +++++++++++ man/glide.lock | 52 +++++++++++++++++++++++++++++++++++++ man/glide.yaml | 12 +++++++++ 11 files changed, 164 insertions(+), 38 deletions(-) create mode 100644 man/generate.go create mode 100755 man/generate.sh create mode 100644 man/glide.lock create mode 100644 man/glide.yaml diff --git a/Makefile b/Makefile index 343c065ac9..eedb0f896d 100644 --- a/Makefile +++ b/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) diff --git a/cli/cobraadaptor/adaptor.go b/cli/cobraadaptor/adaptor.go index 26ec56ef55..04c705cd21 100644 --- a/cli/cobraadaptor/adaptor.go +++ b/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}} diff --git a/hack/make/build-deb b/hack/make/build-deb index 4470913c70..41b2eda94c 100644 --- a/hack/make/build-deb +++ b/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}" diff --git a/hack/make/build-rpm b/hack/make/build-rpm index 3a82a3827c..995dcd8bba 100644 --- a/hack/make/build-rpm +++ b/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 diff --git a/hack/make/ubuntu b/hack/make/ubuntu index 0421dc367d..7033dd5484 100644 --- a/hack/make/ubuntu +++ b/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 - 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 diff --git a/man/Dockerfile b/man/Dockerfile index e513ed1a12..d4eb76ad6b 100644 --- a/man/Dockerfile +++ b/man/Dockerfile @@ -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"] diff --git a/man/README.md b/man/README.md index 922bc3cc74..4b6f90b2a0 100644 --- a/man/README.md +++ b/man/README.md @@ -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 diff --git a/man/generate.go b/man/generate.go new file mode 100644 index 0000000000..7bcc57009e --- /dev/null +++ b/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()) + } +} diff --git a/man/generate.sh b/man/generate.sh new file mode 100755 index 0000000000..e4126ba4ac --- /dev/null +++ b/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 diff --git a/man/glide.lock b/man/glide.lock new file mode 100644 index 0000000000..0d34c2c5a9 --- /dev/null +++ b/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: [] diff --git a/man/glide.yaml b/man/glide.yaml new file mode 100644 index 0000000000..e99b2670d8 --- /dev/null +++ b/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