From cd95e0a5c534a34fc6c2e94b54e4a72f73fa5129 Mon Sep 17 00:00:00 2001 From: Mary Anthony Date: Sat, 24 Oct 2015 18:07:08 -0700 Subject: [PATCH] Tweaking some things Signed-off-by: Mary Anthony --- docs/README.md | 39 ++++++++++++++++----------------------- 1 file changed, 16 insertions(+), 23 deletions(-) diff --git a/docs/README.md b/docs/README.md index 96ded0c51a..de40d98864 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,7 +18,7 @@ Docker has two primary branches for documentation: | Branch | Description | URL (published via commit-hook) | |----------|--------------------------------|------------------------------------------------------------------------------| | `docs` | Official release documentation | [https://docs.docker.com](https://docs.docker.com) | -| `master` | Merged but unreleased development work | [http://docs.master.dockerproject.org](http://docs.master.dockerproject.org) | +| `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 @@ -26,9 +26,7 @@ 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. Docker's CI system automatically builds and updates -the `master` documentation after each merge and posts it to -[http://docs.master.dockerproject.org](http://docs.master.dockerproject.org). +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`, @@ -58,7 +56,7 @@ own. 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. + into the `docs` release branch. 4. Modify existing or add new `.md` files to the `docs` directory. @@ -67,17 +65,16 @@ own. 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` at the root of your `docker/docker` - fork: - + 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. @@ -166,7 +163,7 @@ If this happens, set the Docker host. Run the following command to get the variables in your shell: docker-machine env - + Then, set your environment accordingly. ## Cherry-picking documentation changes to update an existing release. @@ -182,13 +179,13 @@ For example, to update the current release's docs, do the following: 1. Go to your `docker/docker` fork and get the latest from master. $ git fetch upstream - + 2. 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 - + 3. In a browser window, open [https://github.com/docker/docker/commits/master]. 4. Locate the merges you want to publish. @@ -200,9 +197,9 @@ For example, to update the current release's docs, do the following: 5. Copy the commit SHA from GitHub. 6. Cherry-pick the commit. - + $ git cherry-pick -x fe845c4 - + 7. Repeat until you have cherry-picked everything you want to merge. 8. Push your changes to your fork. @@ -224,13 +221,13 @@ For example, to update the current release's docs, do the following: 13. Fetch your merged pull request from `docs`. $ git fetch upstream/docs - + 14. Ensure your branch is clean and set to the latest. $ git reset --hard upstream/docs - + 15. Copy the `awsconfig` file into the `docs` directory. - + 16. Make the beta documentation $ make AWS_S3_BUCKET=beta-docs.docker.io BUILD_ROOT=yes docs-release @@ -284,12 +281,8 @@ aws cloudfront create-invalidation --profile docs.docker.com --distribution-id 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"}' ``` -### Generate the man pages +### Generate the man pages For information on generating man pages (short for manual page), see the README.md document in [the man page directory](https://github.com/docker/docker/tree/master/docker) in this project. - - - -