|
@@ -1,156 +1,255 @@
|
|
|
# Docker Documentation
|
|
|
|
|
|
-The source for Docker documentation is here under `sources/` and uses extended
|
|
|
-Markdown, as implemented by [MkDocs](http://mkdocs.org).
|
|
|
+The source for Docker documentation is in this directory under `sources/`. Our
|
|
|
+documentation uses extended Markdown, as implemented by
|
|
|
+[MkDocs](http://mkdocs.org). The current release of the Docker documentation
|
|
|
+resides on [http://docs.docker.com](http://docs.docker.com).
|
|
|
|
|
|
-The HTML files are built and hosted on
|
|
|
-[http://docs.docker.com](http://docs.docker.com), and update automatically
|
|
|
-after each change to the `docs` branch of [Docker on
|
|
|
-GitHub](https://github.com/docker/docker) thanks to post-commit hooks.
|
|
|
+## Understanding the documentation branches and processes
|
|
|
|
|
|
-## Contributing
|
|
|
+Docker has two primary branches for documentation:
|
|
|
|
|
|
-Be sure to follow the [contribution guidelines](../CONTRIBUTING.md).
|
|
|
-In particular, [remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
|
|
|
+| Branch | Description | URL (published via commit-hook) |
|
|
|
+|----------|--------------------------------|------------------------------------------------------------------------------|
|
|
|
+| `docs` | Official release documentation | [http://docs.docker.com](http://docs.docker.com) |
|
|
|
+| `master` | Merged but unreleased development work | [http://docs.master.dockerproject.com](http://docs.master.dockerproject.com) |
|
|
|
|
|
|
-## Getting Started
|
|
|
+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.
|
|
|
|
|
|
-Docker documentation builds are done in a Docker container, which installs all
|
|
|
-the required tools, adds the local `docs/` directory and builds the HTML docs.
|
|
|
-It then starts a HTTP server on port 8000 so that you can connect and see your
|
|
|
-changes.
|
|
|
+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.com](http://docs.master.dockerproject.com).
|
|
|
|
|
|
-In the root of the `docker` source directory:
|
|
|
+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.
|
|
|
|
|
|
- $ 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.
|
|
|
+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 have any issues you need to debug, you can use `make docs-shell` and then
|
|
|
-run `mkdocs serve`
|
|
|
+### Quickstart for documentation contributors
|
|
|
+
|
|
|
+If you are a new or beginner contributor, we encourage you to read through the
|
|
|
+[our detailed contributors
|
|
|
+guide](https://docs.docker.com/project/who-written-for/). 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:
|
|
|
+
|
|
|
+1. Fork the `docker/docker` repository.
|
|
|
+
|
|
|
+2. Clone the repository to your local machine.
|
|
|
+
|
|
|
+3. Select an issue from `docker/docker` to work on or submit a proposal of your
|
|
|
+own.
|
|
|
+
|
|
|
+4. 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.
|
|
|
+
|
|
|
+4. Modify existing or add new `.md` files to the `docs/sources` directory.
|
|
|
|
|
|
-## Testing the links
|
|
|
+ If you add a new document (`.md`) file, you must also add it to the
|
|
|
+ appropriate section of the `docs/mkdocs.yml` file in this repository.
|
|
|
|
|
|
-You can use `make docs-test` to generate a report of missing links that are referenced in
|
|
|
-the documentation - there should be none.
|
|
|
|
|
|
-## Adding a new document
|
|
|
+5. As you work, build the documentation site locally to see your changes.
|
|
|
|
|
|
-New document (`.md`) files are added to the documentation builds by adding them
|
|
|
-to the menu definition in the `docs/mkdocs.yml` file.
|
|
|
+ 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:
|
|
|
+
|
|
|
+ $ 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 are running Boot2Docker, use the `boot2docker ip`
|
|
|
+ to get the address of your server.
|
|
|
+
|
|
|
+6. Check your writing for style and mechanical errors.
|
|
|
+
|
|
|
+ Use our [documentation style
|
|
|
+ guide](https://docs.docker.com/project/doc-style/) to check style. There are
|
|
|
+ several [good grammar and spelling online
|
|
|
+ checkers](http://www.hemingwayapp.com/) that can check your writing
|
|
|
+ mechanics.
|
|
|
+
|
|
|
+7. Squash your commits on your branch.
|
|
|
+
|
|
|
+8. Make a pull request from your fork back to Docker's `master` branch.
|
|
|
+
|
|
|
+9. Work with the reviewers until your change is approved and merged.
|
|
|
+
|
|
|
+### Debugging and testing
|
|
|
+
|
|
|
+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.
|
|
|
|
|
|
## Style guide
|
|
|
|
|
|
-If you have questions about how to write for Docker's documentation (e.g.,
|
|
|
-questions about grammar, syntax, formatting, styling, language, or tone) please
|
|
|
-see the [style guide](sources/contributing/docs_style-guide.md). If something
|
|
|
-isn't clear in the guide, please submit a PR to help us improve it.
|
|
|
+If you have questions about how to write for Docker's documentation, please see
|
|
|
+the [style guide](sources/project/doc-style.md). 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.
|
|
|
|
|
|
-## Working using GitHub's file editor
|
|
|
|
|
|
-Alternatively, for small changes and typos you might want to use GitHub's built-
|
|
|
-in file editor. It allows you to preview your changes right on-line (though
|
|
|
-there can be some differences between GitHub Markdown and [MkDocs
|
|
|
-Markdown](http://www.mkdocs.org/user-guide/writing-your-docs/)). Just be
|
|
|
-careful not to create many commits. And you must still [sign your
|
|
|
-work!](../CONTRIBUTING.md#sign-your-work)
|
|
|
+## Publishing documentation (for Docker maintainers)
|
|
|
|
|
|
-## Branches
|
|
|
+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.
|
|
|
|
|
|
-| Branch | Description | URL (published via commit-hook) |
|
|
|
-|----------|--------------------------------|------------------------------------------------------------------------------|
|
|
|
-| `docs` | Official release documentation | [http://docs.docker.com](http://docs.docker.com) |
|
|
|
-| `master` | Unreleased development work | [http://docs.master.dockerproject.com](http://docs.master.dockerproject.com) |
|
|
|
+The process for publishing is to build first to an AWS bucket, verify the build,
|
|
|
+and then publish the final release.
|
|
|
|
|
|
-**There are two branches related to editing docs**: `master` and `docs`. You
|
|
|
-should always edit the documentation on a local branch of the `master` branch,
|
|
|
-and send a PR against `master`. That way your fixes will automatically get
|
|
|
-included in later releases, and docs maintainers can easily cherry-pick your
|
|
|
-changes into the `docs` release branch. In the rare case where your change is
|
|
|
-not forward-compatible, you may need to base your changes on the `docs` branch.
|
|
|
+1. Have Docker installed and running on your machine.
|
|
|
|
|
|
-Also, since there is a separate `docs` branch, we can keep
|
|
|
-[http://docs.docker.com](http://docs.docker.com) up to date with any bugs found
|
|
|
-between Docker code releases.
|
|
|
+2. Ask the core maintainers for the `awsconfig` file.
|
|
|
|
|
|
-## Publishing Documentation
|
|
|
+3. Copy the `awsconfig` file to the `docs/` directory.
|
|
|
|
|
|
-To publish a copy of the 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 `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:
|
|
|
|
|
|
-The release script will create an s3 if needed, and will then push the files to it.
|
|
|
+ [profile dowideit-docs]
|
|
|
+ aws_access_key_id = IHOIUAHSIDH234rwf....
|
|
|
+ aws_secret_access_key = OIUYSADJHLKUHQWIUHE......
|
|
|
+ region = ap-southeast-2
|
|
|
|
|
|
- [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.
|
|
|
|
|
|
-The `profile` name must be the same as the name of the bucket you are deploying
|
|
|
-to - which you call from the `docker` directory:
|
|
|
+4. Call the `make` from the `docker` directory.
|
|
|
|
|
|
- make AWS_S3_BUCKET=dowideit-docs docs-release
|
|
|
+ $ make AWS_S3_BUCKET=dowideit-docs docs-release
|
|
|
|
|
|
-This will publish _only_ to the `http://bucket-url/v1.2/` version of the
|
|
|
-documentation.
|
|
|
+ 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
|
|
|
+5. 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
|
|
|
+ $ make AWS_S3_BUCKET=dowideit-docs BUILD_ROOT=yes docs-release
|
|
|
|
|
|
-> **Note:**
|
|
|
-> if you are using Boot2Docker on OSX and the above command returns an 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', you need to set the Docker
|
|
|
-> host. Run `eval "$(boot2docker shellinit)"` to see the correct variable to set. The command
|
|
|
-> will return the full `export` command, so you can just cut and paste.
|
|
|
+### Errors publishing using Boot2Docker
|
|
|
+
|
|
|
+Sometimes, in a Boot2Docker 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 set the
|
|
|
+variables in your shell:
|
|
|
+
|
|
|
+ $ eval "$(boot2docker shellinit)"
|
|
|
|
|
|
## Cherry-picking documentation changes to update an existing release.
|
|
|
|
|
|
-Whenever the core team makes a release, they publish the documentation based
|
|
|
-on the `release` branch (which is copied into the `docs` branch). The
|
|
|
-documentation team can make updates in the meantime, by cherry-picking changes
|
|
|
-from `master` into any of the docs branches.
|
|
|
+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:
|
|
|
+
|
|
|
+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.
|
|
|
+
|
|
|
+ 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.
|
|
|
+
|
|
|
+5. Copy the commit SHA from GitHub.
|
|
|
|
|
|
-For example, to update the current release's docs:
|
|
|
+6. Cherry-pick the commit.
|
|
|
+
|
|
|
+ $ git cherry-pick -x fe845c4
|
|
|
+
|
|
|
+7. Repeat until you have cherry-picked everything you want to merge.
|
|
|
|
|
|
- git fetch upstream
|
|
|
- git checkout -b post-1.2.0-docs-update-1 upstream/docs
|
|
|
- # Then go through the Merge commit linked to PR's (making sure they apply
|
|
|
- to that release)
|
|
|
- # see https://github.com/docker/docker/commits/master
|
|
|
- git cherry-pick -x fe845c4
|
|
|
- # Repeat until you have cherry picked everything you will propose to be merged
|
|
|
- git push upstream post-1.2.0-docs-update-1
|
|
|
+8. Push your changes to your fork.
|
|
|
|
|
|
-Then make a pull request to merge into the `docs` branch, __NOT__ into master.
|
|
|
+ $ git push origin post-1.2.0-docs-update-1
|
|
|
|
|
|
-Once the PR has the needed `LGTM`s, merge it, then publish to our beta server
|
|
|
-to test:
|
|
|
+9. Make a pull request to merge into the `docs` branch.
|
|
|
|
|
|
- git fetch upstream
|
|
|
- git checkout docs
|
|
|
- git reset --hard upstream/docs
|
|
|
- make AWS_S3_BUCKET=beta-docs.docker.io BUILD_ROOT=yes docs-release
|
|
|
+ Do __NOT__ merge into `master`.
|
|
|
|
|
|
-Then go to http://beta-docs.docker.io.s3-website-us-west-2.amazonaws.com/
|
|
|
-to view your results and make sure what you published is what you wanted.
|
|
|
+10. Have maintainers review your pull request.
|
|
|
|
|
|
-When you're happy with it, publish the docs to our live site:
|
|
|
+11. Once the PR has the needed "LGTMs", merge it on GitHub.
|
|
|
|
|
|
- make AWS_S3_BUCKET=docs.docker.com BUILD_ROOT=yes DISTRIBUTION_ID=C2K6......FL2F docs-release
|
|
|
+12. Return to your local fork and make sure you are still on the `docs` branch.
|
|
|
|
|
|
-Test the uncached version of the live docs at http://docs.docker.com.s3-website-us-east-1.amazonaws.com/
|
|
|
+ $ git checkout docs
|
|
|
+
|
|
|
+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
|
|
|
|
|
|
-Note that the new docs will not appear live on the site until the cache (a complex,
|
|
|
-distributed CDN system) is flushed. The `make docs-release` command will do this
|
|
|
-_if_ the `DISTRIBUTION_ID` is set to the Cloudfront distribution ID (ask the meta
|
|
|
-team) - this will take at least 15 minutes to run and you can check its progress
|
|
|
-with the CDN Cloudfront Chrome addin.
|
|
|
+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
|
|
|
+
|
|
|
+17. Open [the beta
|
|
|
+website](http://beta-docs.docker.io.s3-website-us-west-2.amazonaws.com/) site
|
|
|
+and make sure what you published is correct.
|
|
|
+
|
|
|
+19. 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
|
|
|
+
|
|
|
+20. Test the uncached version of the live docs at [http://docs.docker.com.s3-website-us-east-1.amazonaws.com/]
|
|
|
+
|
|
|
+
|
|
|
+### Caching and the docs
|
|
|
+
|
|
|
+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.
|
|
|
|
|
|
## Removing files from the docs.docker.com site
|
|
|
|