github.com/dlintw/docker@v1.5.0-rc4/docs/README.md (about)

     1  # Docker Documentation
     2  
     3  The source for Docker documentation is here under `sources/` and uses extended
     4  Markdown, as implemented by [MkDocs](http://mkdocs.org).
     5  
     6  The HTML files are built and hosted on `https://docs.docker.com`, and update
     7  automatically after each change to the master or release branch of [Docker on
     8  GitHub](https://github.com/docker/docker) thanks to post-commit hooks. The
     9  `docs` branch maps to the "latest" documentation and the `master` (unreleased
    10  development) branch maps to the "master" documentation.
    11  
    12  ## Contributing
    13  
    14  Be sure to follow the [contribution guidelines](../CONTRIBUTING.md).
    15  In particular, [remember to sign your work!](../CONTRIBUTING.md#sign-your-work)
    16  
    17  ## Getting Started
    18  
    19  Docker documentation builds are done in a Docker container, which installs all
    20  the required tools, adds the local `docs/` directory and builds the HTML docs.
    21  It then starts a HTTP server on port 8000 so that you can connect and see your
    22  changes.
    23  
    24  In the root of the `docker` source directory:
    25  
    26      $ make docs
    27      .... (lots of output) ....
    28      docker run --rm -it  -e AWS_S3_BUCKET -p 8000:8000 "docker-docs:master" mkdocs serve
    29      Running at: http://0.0.0.0:8000/
    30      Live reload enabled.
    31      Hold ctrl+c to quit.
    32  
    33  If you have any issues you need to debug, you can use `make docs-shell` and then
    34  run `mkdocs serve`
    35  
    36  ## Testing the links
    37  
    38  You can use `make docs-test` to generate a report of missing links that are referenced in
    39  the documentation - there should be none.
    40  
    41  ## Adding a new document
    42  
    43  New document (`.md`) files are added to the documentation builds by adding them
    44  to the menu definition in the `docs/mkdocs.yml` file.
    45  
    46  ## Style guide
    47  
    48  If you have questions about how to write for Docker's documentation (e.g.,
    49  questions about grammar, syntax, formatting, styling, language, or tone) please
    50  see the [style guide](sources/contributing/docs_style-guide.md). If something
    51  isn't clear in the guide, please submit a PR to help us improve it.
    52  
    53  ## Working using GitHub's file editor
    54  
    55  Alternatively, for small changes and typos you might want to use GitHub's built-
    56  in file editor. It allows you to preview your changes right on-line (though
    57  there can be some differences between GitHub Markdown and [MkDocs
    58  Markdown](http://www.mkdocs.org/user-guide/writing-your-docs/)).  Just be
    59  careful not to create many commits. And you must still [sign your
    60  work!](../CONTRIBUTING.md#sign-your-work)
    61  
    62  ## Branches
    63  
    64  **There are two branches related to editing docs**: `master` and `docs`. You
    65  should always edit the documentation on a local branch of the `master`
    66  branch, and send a PR against `master`.
    67  
    68  That way your fixes will automatically get included in later releases, and docs
    69  maintainers can easily cherry-pick your changes into the `docs` release branch.
    70  In the rare case where your change is not forward-compatible, you may need to
    71  base your changes on the `docs` branch.
    72  
    73  Also, now that we have a `docs` branch, we can keep the
    74  [http://docs.docker.com](http://docs.docker.com) docs up to date with any bugs
    75  found between Docker code releases.
    76  
    77  > **Warning**: When *reading* the docs, the
    78  > [http://docs-stage.docker.com](http://docs-stage.docker.com) documentation may
    79  > include features not yet part of any official Docker release. The `beta-docs`
    80  > site should be used only for understanding bleeding-edge development and
    81  > `docs.docker.com` (which points to the `docs` branch`) should be used for the
    82  > latest official release.
    83  
    84  ## Publishing Documentation
    85  
    86  To publish a copy of the documentation you need to have Docker up and running on
    87  your machine. You'll also need a `docs/awsconfig` file containing the settings
    88  you need to access the AWS bucket you'll be deploying to.
    89  
    90  The release script will create an s3 if needed, and will then push the files to it.
    91  
    92      [profile dowideit-docs] aws_access_key_id = IHOIUAHSIDH234rwf....
    93      aws_secret_access_key = OIUYSADJHLKUHQWIUHE......  region = ap-southeast-2
    94  
    95  The `profile` name must be the same as the name of the bucket you are deploying
    96  to - which you call from the `docker` directory:
    97  
    98      make AWS_S3_BUCKET=dowideit-docs docs-release
    99  
   100  This will publish _only_ to the `http://bucket-url/v1.2/` version of the
   101  documentation.
   102  
   103  If you're publishing the current release's documentation, you need to
   104  also update the root docs pages by running
   105  
   106      make AWS_S3_BUCKET=dowideit-docs BUILD_ROOT=yes docs-release
   107  
   108  > **Note:**
   109  > if you are using Boot2Docker on OSX and the above command returns an error,
   110  > `Post http:///var/run/docker.sock/build?rm=1&t=docker-docs%3Apost-1.2.0-docs_update-2:
   111  > dial unix /var/run/docker.sock: no such file or directory', you need to set the Docker
   112  > host. Run `$(boot2docker shellinit)` to see the correct variable to set. The command
   113  > will return the full `export` command, so you can just cut and paste.
   114  
   115  ## Cherry-picking documentation changes to update an existing release.
   116  
   117  Whenever the core team makes a release, they publish the documentation based
   118  on the `release` branch (which is copied into the `docs` branch). The
   119  documentation team can make updates in the meantime, by cherry-picking changes
   120  from `master` into any of the docs branches.
   121  
   122  For example, to update the current release's docs:
   123  
   124      git fetch upstream
   125      git checkout -b post-1.2.0-docs-update-1 upstream/docs
   126      # Then go through the Merge commit linked to PR's (making sure they apply
   127      to that release)
   128      # see https://github.com/docker/docker/commits/master
   129      git cherry-pick -x fe845c4
   130      # Repeat until you have cherry picked everything you will propose to be merged
   131      git push upstream post-1.2.0-docs-update-1
   132  
   133  Then make a pull request to merge into the `docs` branch, __NOT__ into master.
   134  
   135  Once the PR has the needed `LGTM`s, merge it, then publish to our beta server
   136  to test:
   137  
   138      git fetch upstream
   139      git checkout docs
   140      git reset --hard upstream/docs
   141      make AWS_S3_BUCKET=beta-docs.docker.io BUILD_ROOT=yes docs-release
   142  
   143  Then go to http://beta-docs.docker.io.s3-website-us-west-2.amazonaws.com/
   144  to view your results and make sure what you published is what you wanted.
   145  
   146  When you're happy with it, publish the docs to our live site:
   147  
   148      make AWS_S3_BUCKET=docs.docker.com BUILD_ROOT=yes DISTRIBUTION_ID=C2K6......FL2F docs-release
   149  
   150  Test the uncached version of the live docs at http://docs.docker.com.s3-website-us-east-1.amazonaws.com/
   151      
   152  Note that the new docs will not appear live on the site until the cache (a complex,
   153  distributed CDN system) is flushed. The `make docs-release` command will do this
   154  _if_ the `DISTRIBUTION_ID` is set to the Cloudfront distribution ID (ask the meta
   155  team) - this will take at least 15 minutes to run and you can check its progress
   156  with the CDN Cloudfront Chrome addin.
   157