2014-04-16 18:07:55 +00:00
|
|
|
Docker Documentation
|
|
|
|
====================
|
|
|
|
|
2014-04-17 15:36:58 +00:00
|
|
|
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.
|
2014-04-16 18:07:55 +00:00
|
|
|
|
2014-04-17 15:36:58 +00:00
|
|
|
# Generating man pages from the Markdown files
|
2014-04-16 18:07:55 +00:00
|
|
|
|
2014-08-05 00:59:37 +00:00
|
|
|
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.
|
2014-04-16 18:07:55 +00:00
|
|
|
|
2014-08-05 00:59:37 +00:00
|
|
|
## Building the md2man image
|
2014-04-16 18:07:55 +00:00
|
|
|
|
2014-08-05 00:59:37 +00:00
|
|
|
There is a `Dockerfile` provided in the `docker/docs/man` directory.
|
2014-04-16 18:07:55 +00:00
|
|
|
|
2014-08-05 00:59:37 +00:00
|
|
|
Using this `Dockerfile`, create a Docker image tagged `docker/md2man`:
|
2014-04-16 18:07:55 +00:00
|
|
|
|
2014-08-05 00:59:37 +00:00
|
|
|
docker build -t docker/md2man .
|
2014-04-16 18:07:55 +00:00
|
|
|
|
2014-08-05 00:59:37 +00:00
|
|
|
## Utilizing the image
|
2014-04-21 20:28:25 +00:00
|
|
|
|
2014-04-17 19:52:13 +00:00
|
|
|
Once the image is built, run a container using the image with *volumes*:
|
2014-04-16 18:07:55 +00:00
|
|
|
|
2014-08-05 00:59:37 +00:00
|
|
|
docker run -v /<path-to-git-dir>/docker/docs/man:/docs:rw \
|
|
|
|
-w /docs -i docker/md2man /docs/md2man-all.sh
|
2014-04-16 18:07:55 +00:00
|
|
|
|
2014-08-05 00:59:37 +00:00
|
|
|
The `md2man` Docker container will process the Markdown files and generate
|
2014-06-25 16:04:59 +00:00
|
|
|
the man pages inside the `docker/docs/man/man1` directory using
|
2014-04-17 19:36:22 +00:00
|
|
|
Docker volumes. For more information on Docker volumes see the man page for
|
2014-04-21 20:28:25 +00:00
|
|
|
`docker run` and also look at the article [Sharing Directories via Volumes]
|
2014-07-02 00:30:25 +00:00
|
|
|
(http://docs.docker.com/use/working_with_volumes/).
|