Skip to content

Commit 05d7008

Browse files
corherecorhere
committed
man: build dockerd man pages using make
Vendor the go-md2man tool used to generate the man pages so that the only dependency is a Go toolchain. Signed-off-by: Cory Snider <[email protected]>
1 parent b4cee5c commit 05d7008

31 files changed

Lines changed: 8979 additions & 22 deletions

‎man/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/man*
2+
/.build

‎man/Makefile‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
prefix = /usr/local
2+
mandir = $(prefix)/man
3+
INSTALL = install
4+
INSTALL_DATA = ${INSTALL} -m 644
5+
6+
ALL_PAGES := $(wildcard *.*.md)
7+
8+
# Determine which manual sections we are generating pages for
9+
# by isolating the last part of the filename before the extension
10+
# and eliminating duplicates.
11+
man_section = $(lastword $(subst ., ,$(1)))
12+
sections := $(sort $(foreach page,$(ALL_PAGES:.md=),$(call man_section,$(page))))
13+
14+
# Dynamically generate pattern rules for each manual section
15+
# so make knows how to build a target like man8/dockerd.8.
16+
define MANPAGE_template
17+
man$(1)/%.$(1): %.$(1).md .build/go-md2man | man$(1)
18+
.build/go-md2man -in $$< -out $$@
19+
endef
20+
$(foreach sec,$(sections),$(eval $(call MANPAGE_template,$(sec))))
21+
22+
# Default target: build all man pages.
23+
all: $(foreach page,$(ALL_PAGES:.md=),man$(call man_section,$(page))/$(page))
24+
25+
# Target for creating the man{1..8} directories as needed.
26+
.PRECIOUS: man%
27+
man%:
28+
-mkdir $@
29+
30+
.PHONY: install
31+
install: all
32+
for sec in $(sections); do \
33+
$(INSTALL_DATA) man$$sec/* $(DESTDIR)$(mandir)/man$$sec; \
34+
done
35+
36+
.build/go-md2man: go.mod go.sum
37+
GO111MODULE=auto go build -o $@ github.com/cpuguy83/go-md2man/v2
38+
39+
.PHONY: clean
40+
clean:
41+
rm -r man* .build

‎man/README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
Docker Engine Documentation
2+
===========================
3+
4+
The man pages for Docker Engine are generated from the markdown sources and tooling in this directory.
5+
6+
## Generate the man pages
7+
8+
Run `make` from within this directory.
9+
A Go toolchain is required.
10+
The generated man pages will be placed in man*N* subdirectories, where *N* is the manual section number.
11+
12+
## Install the man pages
13+
14+
Run `make install` from within this directory.
15+
The make variables `prefix`, `mandir`, `INSTALL`, `INSTALL_DATA` and `DESTDIR`
16+
are supported for customizing the installation.
17+
18+
## Add a new man page
19+
20+
Create a new Markdown file in this directory with a filename *TITLE*.*SECTION*.md,
21+
where *TITLE* is the man page title and *SECTION* is the section number.
22+
The Makefile will pick it up automatically.
23+
24+
The Makefile ignores Markdown files that do not match the glob `*.*.md`,
25+
allowing non-manpage documentation (like this README file) to coexist.

‎man/go.mod‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
module github.com/docker/docker/man
2+
3+
go 1.19
4+
5+
require github.com/cpuguy83/go-md2man/v2 v2.0.4
6+
7+
require github.com/russross/blackfriday/v2 v2.1.0 // indirect

‎man/go.sum‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
github.com/cpuguy83/go-md2man/v2 v2.0.4 h1:wfIWP927BUkWJb2NmU/kNDYIBTh/ziUX91+lVfRxZq4=
2+
github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
3+
github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
4+
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=

‎man/md2man-all.sh‎

Lines changed: 0 additions & 22 deletions
This file was deleted.

‎man/tools.go‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
//go:build tools
2+
3+
package man
4+
5+
import (
6+
_ "github.com/cpuguy83/go-md2man/v2"
7+
)

‎man/vendor/github.com/cpuguy83/go-md2man/v2/.gitignore‎

Lines changed: 2 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎man/vendor/github.com/cpuguy83/go-md2man/v2/.golangci.yml‎

Lines changed: 6 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎man/vendor/github.com/cpuguy83/go-md2man/v2/Dockerfile‎

Lines changed: 14 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)