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