зеркало из https://github.com/microsoft/docker.git
Merge pull request #11222 from moxiegirl/update-howto-docs
Updating in light of new contributors guide. Got verbal ok from Jess to pull janky is acting janky.
This commit is contained in:
moxiegirl
Коммит
4abc0fcf59
339
docs/README.md
339
docs/README.md
|
|
@ -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
|
||||
|
||||
Be sure to follow the [contribution guidelines](../CONTRIBUTING.md).
|
||||
In particular, [remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
|
||||
|
||||
## Getting Started
|
||||
|
||||
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.
|
||||
|
||||
In the root of the `docker` source directory:
|
||||
|
||||
$ 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.
|
||||
|
||||
If you have any issues you need to debug, you can use `make docs-shell` and then
|
||||
run `mkdocs serve`
|
||||
|
||||
## Testing the links
|
||||
|
||||
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
|
||||
|
||||
New document (`.md`) files are added to the documentation builds by adding them
|
||||
to the menu definition in the `docs/mkdocs.yml` file.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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)
|
||||
|
||||
## Branches
|
||||
Docker has two primary branches for documentation:
|
||||
|
||||
| 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) |
|
||||
| `master` | Merged but unreleased development work | [http://docs.master.dockerproject.com](http://docs.master.dockerproject.com) |
|
||||
|
||||
**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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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).
|
||||
|
||||
## Publishing Documentation
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
The release script will create an s3 if needed, and will then push the files to it.
|
||||
### Quickstart for documentation contributors
|
||||
|
||||
[profile dowideit-docs]
|
||||
aws_access_key_id = IHOIUAHSIDH234rwf....
|
||||
aws_secret_access_key = OIUYSADJHLKUHQWIUHE......
|
||||
region = ap-southeast-2
|
||||
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 `profile` name must be the same as the name of the bucket you are deploying
|
||||
to - which you call from the `docker` directory:
|
||||
The following is the essential workflow for contributing to the documentation:
|
||||
|
||||
make AWS_S3_BUCKET=dowideit-docs docs-release
|
||||
1. Fork the `docker/docker` repository.
|
||||
|
||||
This will publish _only_ to the `http://bucket-url/v1.2/` version of the
|
||||
documentation.
|
||||
2. Clone the repository to your local machine.
|
||||
|
||||
If you're publishing the current release's documentation, you need to
|
||||
also update the root docs pages by running
|
||||
3. Select an issue from `docker/docker` to work on or submit a proposal of your
|
||||
own.
|
||||
|
||||
make AWS_S3_BUCKET=dowideit-docs BUILD_ROOT=yes docs-release
|
||||
4. Create a feature branch from `master` in which to work.
|
||||
|
||||
> **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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
5. 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` 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, 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.
|
||||
|
||||
|
||||
## Publishing documentation (for Docker maintainers)
|
||||
|
||||
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.
|
||||
|
||||
1. Have Docker installed and running on your machine.
|
||||
|
||||
2. Ask the core maintainers for the `awsconfig` file.
|
||||
|
||||
3. 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.
|
||||
|
||||
4. 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.
|
||||
|
||||
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
|
||||
|
||||
### 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:
|
||||
For example, to update the current release's docs, do the following:
|
||||
|
||||
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
|
||||
1. Go to your `docker/docker` fork and get the latest from master.
|
||||
|
||||
Then make a pull request to merge into the `docs` branch, __NOT__ into master.
|
||||
$ git fetch upstream
|
||||
|
||||
2. Checkout a new branch based on `upstream/docs`.
|
||||
|
||||
Once the PR has the needed `LGTM`s, merge it, then publish to our beta server
|
||||
to test:
|
||||
You should give your new branch a descriptive name.
|
||||
|
||||
git fetch upstream
|
||||
git checkout docs
|
||||
git reset --hard upstream/docs
|
||||
make AWS_S3_BUCKET=beta-docs.docker.io BUILD_ROOT=yes docs-release
|
||||
$ 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].
|
||||
|
||||
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.
|
||||
4. Locate the merges you want to publish.
|
||||
|
||||
When you're happy with it, publish the docs to our live site:
|
||||
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.
|
||||
|
||||
make AWS_S3_BUCKET=docs.docker.com BUILD_ROOT=yes DISTRIBUTION_ID=C2K6......FL2F docs-release
|
||||
5. Copy the commit SHA from GitHub.
|
||||
|
||||
Test the uncached version of the live docs at http://docs.docker.com.s3-website-us-east-1.amazonaws.com/
|
||||
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.
|
||||
|
||||
$ git push origin post-1.2.0-docs-update-1
|
||||
|
||||
9. Make a pull request to merge into the `docs` branch.
|
||||
|
||||
Do __NOT__ merge into `master`.
|
||||
|
||||
10. Have maintainers review your pull request.
|
||||
|
||||
11. Once the PR has the needed "LGTMs", merge it on GitHub.
|
||||
|
||||
12. Return to your local fork and make sure you are still on the `docs` branch.
|
||||
|
||||
$ 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
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче