github.com/circular-dark/docker@v1.7.0/docs/README.md (about)

     1  <!--[metadata]>
     2  +++
     3  draft = true
     4  +++
     5  <![end-metadata]-->
     6  
     7  # Docker Documentation
     8  
     9  The source for Docker documentation is in this directory. Our
    10  documentation uses extended Markdown, as implemented by
    11  [MkDocs](http://mkdocs.org).  The current release of the Docker documentation
    12  resides on [https://docs.docker.com](https://docs.docker.com).
    13  
    14  ## Understanding the documentation branches and processes
    15  
    16  Docker has two primary branches for documentation:
    17  
    18  | Branch   | Description                    | URL (published via commit-hook)                                              |
    19  |----------|--------------------------------|------------------------------------------------------------------------------|
    20  | `docs`   | Official release documentation | [https://docs.docker.com](https://docs.docker.com)                             |
    21  | `master` | Merged but unreleased development work    | [http://docs.master.dockerproject.org](http://docs.master.dockerproject.org) |
    22  
    23  Additions and updates to upcoming releases are made in a feature branch off of
    24  the `master` branch. The Docker maintainers also support a `docs` branch that
    25  contains the last release of documentation.
    26  
    27  After a release, documentation updates are continually merged into `master` as
    28  they occur. This work includes new documentation for forthcoming features, bug
    29  fixes, and other updates. Docker's CI system automatically builds and updates
    30  the `master` documentation after each merge and posts it to
    31  [http://docs.master.dockerproject.org](http://docs.master.dockerproject.org). 
    32  
    33  Periodically, the Docker maintainers update `docs.docker.com` between official
    34  releases of Docker. They do this by cherry-picking commits from `master`,
    35  merging them into `docs`,  and then publishing the result.
    36  
    37  In the rare case where a change is not forward-compatible, changes may be made
    38  on other branches by special arrangement with the Docker maintainers.
    39  
    40  ### Quickstart for documentation contributors
    41  
    42  If you are a new or beginner contributor, we encourage you to read through the
    43  [our detailed contributors
    44  guide](https://docs.docker.com/project/who-written-for/). The guide explains in
    45  detail, with examples, how to contribute. If you are an experienced contributor
    46  this quickstart should be enough to get you started.
    47  
    48  The following is the essential workflow for contributing to the documentation:
    49  
    50  1. Fork the `docker/docker` repository.
    51  
    52  2. Clone the repository to your local machine.
    53  
    54  3. Select an issue from `docker/docker` to work on or submit a proposal of your
    55  own.
    56  
    57  4. Create a feature branch from `master` in which to work.
    58  
    59  	By basing from `master` your work is automatically included in the next
    60  	release. It also allows docs maintainers to easily cherry-pick your changes
    61  	into the `docs` release branch. 
    62  
    63  4. Modify existing or add new `.md` files to the `docs` directory.
    64  
    65  	If you add a new document (`.md`) file, you must also add it to the
    66  	appropriate section of the `docs/mkdocs.yml` file in this repository.
    67  
    68  
    69  5.  As you work, build the documentation site locally to see your changes.
    70  
    71  	The `docker/docker` repository contains a `Dockerfile` and a `Makefile`.
    72  	Together, these create a development environment in which you can build and
    73  	run a container running the Docker documentation website. To build the
    74  	documentation site, enter `make docs` at the root of your `docker/docker`
    75  	fork:
    76  	
    77  		$ make docs
    78  		.... (lots of output) ....
    79  		docker run --rm -it  -e AWS_S3_BUCKET -p 8000:8000 "docker-docs:master" mkdocs serve
    80  		Running at: http://0.0.0.0:8000/
    81  		Live reload enabled.
    82  		Hold ctrl+c to quit.
    83  	
    84  	
    85  	The build creates an image containing all the required tools, adds the local
    86  	`docs/` directory and generates the HTML files. Then, it runs a Docker
    87  	container with this image.
    88  
    89  	The container exposes port 8000 on the localhost so that you can connect and
    90  	see your changes. If you are running Boot2Docker, use the `boot2docker ip`
    91  	to get the address of your server.
    92  
    93  6.  Check your writing for style and mechanical errors.
    94  
    95  	Use our [documentation style
    96  	guide](https://docs.docker.com/project/doc-style/) to check style. There are
    97  	several [good grammar and spelling online
    98  	checkers](http://www.hemingwayapp.com/) that can check your writing
    99  	mechanics.
   100  
   101  7.  Squash your commits on your branch.
   102  
   103  8.  Make a pull request from your fork back to Docker's `master` branch.
   104  
   105  9.  Work with the reviewers until your change is approved and merged.
   106  
   107  ### Debugging and testing
   108  
   109  If you have any issues you need to debug, you can use `make docs-shell` and then
   110  run `mkdocs serve`. You can use `make docs-test` to generate a report of missing
   111  links that are referenced in the documentation&mdash;there should be none.
   112  
   113  ## Style guide
   114  
   115  If you have questions about how to write for Docker's documentation, please see
   116  the [style guide](project/doc-style.md). The style guide provides
   117  guidance about grammar, syntax, formatting, styling, language, or tone. If
   118  something isn't clear in the guide, please submit an issue to let us know or
   119  submit a pull request to help us improve it.
   120  
   121  
   122  ## Publishing documentation (for Docker maintainers)
   123  
   124  To publish Docker's documentation you need to have Docker up and running on your
   125  machine. You'll also need a `docs/awsconfig` file containing the settings you
   126  need to access the AWS bucket you'll be deploying to.
   127  
   128  The process for publishing is to build first to an AWS bucket, verify the build,
   129  and then publish the final release.
   130  
   131  1. Have Docker installed and running on your machine.
   132  
   133  2. Ask the core maintainers for the `awsconfig` file.
   134  
   135  3. Copy the `awsconfig` file to the `docs/` directory.
   136  
   137  	The `awsconfig` file contains the profiles of the S3 buckets for our
   138  	documentation sites. (If needed, the release script creates an S3 bucket and
   139  	pushes the files to it.)  Each profile has this format:
   140  
   141  		[profile dowideit-docs]
   142  		aws_access_key_id = IHOIUAHSIDH234rwf....
   143  		aws_secret_access_key = OIUYSADJHLKUHQWIUHE......
   144  		region = ap-southeast-2
   145  
   146  	The `profile` name must be the same as the name of the bucket you are
   147  	deploying to.
   148  
   149  4. Call the `make` from the `docker` directory.
   150  
   151      	$ make AWS_S3_BUCKET=dowideit-docs docs-release
   152  
   153  	This publishes _only_ to the `http://bucket-url/v1.2/` version of the
   154  	documentation.
   155  
   156  5.  If you're publishing the current release's documentation, you need to also
   157  update the root docs pages by running
   158  
   159       	$ make AWS_S3_BUCKET=dowideit-docs BUILD_ROOT=yes docs-release
   160  
   161  ### Errors publishing using Boot2Docker
   162  
   163  Sometimes, in a Boot2Docker environment, the publishing procedure returns this
   164  error:
   165  
   166  	Post http:///var/run/docker.sock/build?rm=1&t=docker-docs%3Apost-1.2.0-docs_update-2:
   167  	dial unix /var/run/docker.sock: no such file or directory.
   168  
   169  If this happens, set the Docker host. Run the following command to set the
   170  variables in your shell:
   171  
   172  		$ eval "$(boot2docker shellinit)"
   173  
   174  ## Cherry-picking documentation changes to update an existing release.
   175  
   176  Whenever the core team makes a release, they publish the documentation based on
   177  the `release` branch. At that time, the  `release` branch is copied into the
   178  `docs` branch. The documentation team makes updates between Docker releases by
   179  cherry-picking changes from `master` into any of the documentation branches.
   180  Typically, we cherry-pick into the `docs` branch.
   181  
   182  For example, to update the current release's docs, do the following:
   183  
   184  1. Go to your `docker/docker` fork and get the latest from master.
   185  
   186      	$ git fetch upstream
   187          
   188  2. Checkout a new branch based on `upstream/docs`.
   189  
   190  	You should give your new branch a descriptive name.
   191  
   192  		$ git checkout -b post-1.2.0-docs-update-1 upstream/docs
   193  	
   194  3. In a browser window, open [https://github.com/docker/docker/commits/master].
   195  
   196  4. Locate the merges you want to publish.
   197  
   198  	You should only cherry-pick individual commits; do not cherry-pick merge
   199  	commits. To minimize merge conflicts, start with the oldest commit and work
   200  	your way forward in time.
   201  
   202  5. Copy the commit SHA from GitHub.
   203  
   204  6. Cherry-pick the commit.
   205  	
   206  	 	$ git cherry-pick -x fe845c4
   207  	
   208  7. Repeat until you have cherry-picked everything you want to merge.
   209  
   210  8. Push your changes to your fork.
   211  
   212      	$ git push origin post-1.2.0-docs-update-1
   213  
   214  9. Make a pull request to merge into the `docs` branch.
   215  
   216  	Do __NOT__ merge into `master`.
   217  
   218  10. Have maintainers review your pull request.
   219  
   220  11. Once the PR has the needed "LGTMs", merge it on GitHub.
   221  
   222  12. Return to your local fork and make sure you are still on the `docs` branch.
   223  
   224  		$ git checkout docs
   225  
   226  13. Fetch your merged pull request from `docs`.
   227  
   228  		$ git fetch upstream/docs
   229  	
   230  14. Ensure your branch is clean and set to the latest.
   231  
   232     	 	$ git reset --hard upstream/docs
   233      
   234  15. Copy the `awsconfig` file into the `docs` directory.
   235      
   236  16. Make the beta documentation
   237  
   238      	$ make AWS_S3_BUCKET=beta-docs.docker.io BUILD_ROOT=yes docs-release
   239  
   240  17. Open [the beta
   241  website](http://beta-docs.docker.io.s3-website-us-west-2.amazonaws.com/) site
   242  and make sure what you published is correct.
   243  
   244  19. When you're happy with your content, publish the docs to our live site:
   245  
   246     		$ make AWS_S3_BUCKET=docs.docker.com BUILD_ROOT=yes
   247  DISTRIBUTION_ID=C2K6......FL2F docs-release
   248  
   249  20. Test the uncached version of the live docs at [http://docs.docker.com.s3-website-us-east-1.amazonaws.com/]
   250  
   251  
   252  ### Caching and the docs
   253  
   254  New docs do not appear live on the site until the cache (a complex, distributed
   255  CDN system) is flushed. The `make docs-release` command flushes the cache _if_
   256  the `DISTRIBUTION_ID` is set to the Cloudfront distribution ID. The cache flush
   257  can take at least 15 minutes to run and you can check its progress with the CDN
   258  Cloudfront Purge Tool Chrome app.
   259  
   260  ## Removing files from the docs.docker.com site
   261  
   262  Sometimes it becomes necessary to remove files from the historical published documentation.
   263  The most reliable way to do this is to do it directly using `aws s3` commands running in a
   264  docs container:
   265  
   266  Start the docs container like `make docs-shell`, but bind mount in your `awsconfig`:
   267  
   268  ```
   269  docker run --rm -it -v $(CURDIR)/docs/awsconfig:/docs/awsconfig docker-docs:master bash
   270  ```
   271  
   272  and then the following example shows deleting 2 documents from s3, and then requesting the
   273  CloudFlare cache to invalidate them:
   274  
   275  
   276  ```
   277  export BUCKET BUCKET=docs.docker.com
   278  export AWS_CONFIG_FILE=$(pwd)/awsconfig
   279  aws s3 --profile $BUCKET ls s3://$BUCKET
   280  aws s3 --profile $BUCKET rm s3://$BUCKET/v1.0/reference/api/docker_io_oauth_api/index.html
   281  aws s3 --profile $BUCKET rm s3://$BUCKET/v1.1/reference/api/docker_io_oauth_api/index.html
   282  
   283  aws configure set preview.cloudfront true
   284  export DISTRIBUTION_ID=YUTIYUTIUTIUYTIUT
   285  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"}'
   286  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"}'
   287  ```
   288  
   289  ### Generate the man pages 
   290  
   291  For information on generating man pages (short for manual page), see [the man
   292  page directory](https://github.com/docker/docker/tree/master/docker) in this
   293  project.
   294  
   295  
   296