The source for Docker documentation is in this directory. Our documentation uses extended Markdown, as implemented by MkDocs. The current release of the Docker documentation resides on https://docs.docker.com.
Docker has two primary branches for documentation:
Branch | Description | URL (published via commit-hook) |
---|---|---|
docs | Official release documentation | https://docs.docker.com |
master | Merged but unreleased development work |
Additions and updates to upcoming releases are made in a feature branch off of the master
branch. The Docker maintainers also support a docs
branch that contains the last release of documentation.
After a release, documentation updates are continually merged into master
as they occur. This work includes new documentation for forthcoming features, bug fixes, and other updates.
Periodically, the Docker maintainers update docs.docker.com
between official releases of Docker. They do this by cherry-picking commits from master
, merging them into docs
, and then publishing the result.
In the rare case where a change is not forward-compatible, changes may be made on other branches by special arrangement with the Docker maintainers.
If you are a new or beginner contributor, we encourage you to read through the our detailed contributors guide. The guide explains in detail, with examples, how to contribute. If you are an experienced contributor this quickstart should be enough to get you started.
The following is the essential workflow for contributing to the documentation:
Fork the docker/docker
repository.
Clone the repository to your local machine.
Select an issue from docker/docker
to work on or submit a proposal of your own.
Create a feature branch from master
in which to work.
By basing from master
your work is automatically included in the next release. It also allows docs maintainers to easily cherry-pick your changes into the docs
release branch.
Modify existing or add new .md
files to the docs
directory.
As you work, build the documentation site locally to see your changes.
The docker/docker
repository contains a Dockerfile
and a Makefile
. Together, these create a development environment in which you can build and run a container running the Docker documentation website. To build the documentation site, enter make docs
in the docs
directory of your docker/docker
fork:
$ make docs .... (lots of output) .... docker run --rm -it -e AWS_S3_BUCKET -p 8000:8000 "docker-docs:master" mkdocs serve Running at: http://0.0.0.0:8000/ Live reload enabled. Hold ctrl+c to quit.
The build creates an image containing all the required tools, adds the local docs/
directory and generates the HTML files. Then, it runs a Docker container with this image.
The container exposes port 8000 on the localhost so that you can connect and see your changes. If you use Docker Machine, the docker-machine ip <machine-name>
command gives you the address of your server.
Check your writing for style and mechanical errors.
Use our documentation style guide to check style. There are several good grammar and spelling online checkers that can check your writing mechanics.
Squash your commits on your branch.
Make a pull request from your fork back to Docker's master
branch.
Work with the reviewers until your change is approved and merged.
If you have any issues you need to debug, you can use make docs-shell
and then run mkdocs serve
. You can use make docs-test
to generate a report of missing links that are referenced in the documentation—there should be none.
If you have questions about how to write for Docker‘s documentation, please see the style guide. The style guide provides guidance about grammar, syntax, formatting, styling, language, or tone. If something isn’t clear in the guide, please submit an issue to let us know or submit a pull request to help us improve it.
To publish Docker‘s documentation you need to have Docker up and running on your machine. You’ll also need a docs/awsconfig
file containing the settings you need to access the AWS bucket you'll be deploying to.
The process for publishing is to build first to an AWS bucket, verify the build, and then publish the final release.
Have Docker installed and running on your machine.
Ask the core maintainers for the awsconfig
file.
Copy the awsconfig
file to the docs/
directory.
The awsconfig
file contains the profiles of the S3 buckets for our documentation sites. (If needed, the release script creates an S3 bucket and pushes the files to it.) Each profile has this format:
[profile dowideit-docs] aws_access_key_id = IHOIUAHSIDH234rwf.... aws_secret_access_key = OIUYSADJHLKUHQWIUHE...... region = ap-southeast-2
The profile
name must be the same as the name of the bucket you are deploying to.
Call the make
from the docker
directory.
$ make AWS_S3_BUCKET=dowideit-docs docs-release
This publishes only to the http://bucket-url/v1.2/
version of the documentation.
If you‘re publishing the current release’s documentation, you need to also update the root docs pages by running
$ make AWS_S3_BUCKET=dowideit-docs BUILD_ROOT=yes docs-release
Sometimes, in a Windows or Mac environment, the publishing procedure returns this error:
Post http:///var/run/docker.sock/build?rm=1&t=docker-docs%3Apost-1.2.0-docs_update-2: dial unix /var/run/docker.sock: no such file or directory.
If this happens, set the Docker host. Run the following command to get the variables in your shell:
docker-machine env <machine-name>
Then, set your environment accordingly.
Whenever the core team makes a release, they publish the documentation based on the release
branch. At that time, the release
branch is copied into the docs
branch. The documentation team makes updates between Docker releases by cherry-picking changes from master
into any of the documentation branches. Typically, we cherry-pick into the docs
branch.
For example, to update the current release's docs, do the following:
Go to your docker/docker
fork and get the latest from master.
$ git fetch upstream
Checkout a new branch based on upstream/docs
.
You should give your new branch a descriptive name.
$ git checkout -b post-1.2.0-docs-update-1 upstream/docs
In a browser window, open [https://github.com/docker/docker/commits/master].
Locate the merges you want to publish.
You should only cherry-pick individual commits; do not cherry-pick merge commits. To minimize merge conflicts, start with the oldest commit and work your way forward in time.
Copy the commit SHA from GitHub.
Cherry-pick the commit.
$ git cherry-pick -x fe845c4
Repeat until you have cherry-picked everything you want to merge.
Push your changes to your fork.
$ git push origin post-1.2.0-docs-update-1
Make a pull request to merge into the docs
branch.
Do NOT merge into master
.
Have maintainers review your pull request.
Once the PR has the needed “LGTMs”, merge it on GitHub.
Return to your local fork and make sure you are still on the docs
branch.
$ git checkout docs
Fetch your merged pull request from docs
.
$ git fetch upstream/docs
Ensure your branch is clean and set to the latest.
$ git reset --hard upstream/docs
Copy the awsconfig
file into the docs
directory.
Make the beta documentation
$ make AWS_S3_BUCKET=beta-docs.docker.io BUILD_ROOT=yes docs-release
Open the beta website site and make sure what you published is correct.
When you're happy with your content, publish the docs to our live site:
$ make AWS_S3_BUCKET=docs.docker.com BUILD_ROOT=yes
DISTRIBUTION_ID=C2K6......FL2F docs-release
New docs do not appear live on the site until the cache (a complex, distributed CDN system) is flushed. The make docs-release
command flushes the cache if the DISTRIBUTION_ID
is set to the Cloudfront distribution ID. The cache flush can take at least 15 minutes to run and you can check its progress with the CDN Cloudfront Purge Tool Chrome app.
Sometimes it becomes necessary to remove files from the historical published documentation. The most reliable way to do this is to do it directly using aws s3
commands running in a docs container:
Start the docs container like make docs-shell
, but bind mount in your awsconfig
:
docker run --rm -it -v $(CURDIR)/docs/awsconfig:/docs/awsconfig docker-docs:master bash
and then the following example shows deleting 2 documents from s3, and then requesting the CloudFlare cache to invalidate them:
export BUCKET BUCKET=docs.docker.com export AWS_CONFIG_FILE=$(pwd)/awsconfig aws s3 --profile $BUCKET ls s3://$BUCKET aws s3 --profile $BUCKET rm s3://$BUCKET/v1.0/reference/api/docker_io_oauth_api/index.html aws s3 --profile $BUCKET rm s3://$BUCKET/v1.1/reference/api/docker_io_oauth_api/index.html aws configure set preview.cloudfront true export DISTRIBUTION_ID=YUTIYUTIUTIUYTIUT aws cloudfront create-invalidation --profile docs.docker.com --distribution-id $DISTRIBUTION_ID --invalidation-batch '{"Paths":{"Quantity":1, "Items":["/v1.0/reference/api/docker_io_oauth_api/"]},"CallerReference":"6Mar2015sventest1"}' aws cloudfront create-invalidation --profile docs.docker.com --distribution-id $DISTRIBUTION_ID --invalidation-batch '{"Paths":{"Quantity":1, "Items":["/v1.1/reference/api/docker_io_oauth_api/"]},"CallerReference":"6Mar2015sventest1"}'
For information on generating man pages (short for manual page), see the README.md document in the man page directory in this project.