github.com/dougm/docker@v1.5.0/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]
    93      aws_access_key_id = IHOIUAHSIDH234rwf....
    94      aws_secret_access_key = OIUYSADJHLKUHQWIUHE......
    95      region = ap-southeast-2
    96  
    97  The `profile` name must be the same as the name of the bucket you are deploying
    98  to - which you call from the `docker` directory:
    99  
   100      make AWS_S3_BUCKET=dowideit-docs docs-release
   101  
   102  This will publish _only_ to the `http://bucket-url/v1.2/` version of the
   103  documentation.
   104  
   105  If you're publishing the current release's documentation, you need to
   106  also update the root docs pages by running
   107  
   108      make AWS_S3_BUCKET=dowideit-docs BUILD_ROOT=yes docs-release
   109  
   110  > **Note:**
   111  > if you are using Boot2Docker on OSX and the above command returns an error,
   112  > `Post http:///var/run/docker.sock/build?rm=1&t=docker-docs%3Apost-1.2.0-docs_update-2:
   113  > dial unix /var/run/docker.sock: no such file or directory', you need to set the Docker
   114  > host. Run `$(boot2docker shellinit)` to see the correct variable to set. The command
   115  > will return the full `export` command, so you can just cut and paste.
   116  
   117  ## Cherry-picking documentation changes to update an existing release.
   118  
   119  Whenever the core team makes a release, they publish the documentation based
   120  on the `release` branch (which is copied into the `docs` branch). The
   121  documentation team can make updates in the meantime, by cherry-picking changes
   122  from `master` into any of the docs branches.
   123  
   124  For example, to update the current release's docs:
   125  
   126      git fetch upstream
   127      git checkout -b post-1.2.0-docs-update-1 upstream/docs
   128      # Then go through the Merge commit linked to PR's (making sure they apply
   129      to that release)
   130      # see https://github.com/docker/docker/commits/master
   131      git cherry-pick -x fe845c4
   132      # Repeat until you have cherry picked everything you will propose to be merged
   133      git push upstream post-1.2.0-docs-update-1
   134  
   135  Then make a pull request to merge into the `docs` branch, __NOT__ into master.
   136  
   137  Once the PR has the needed `LGTM`s, merge it, then publish to our beta server
   138  to test:
   139  
   140      git fetch upstream
   141      git checkout docs
   142      git reset --hard upstream/docs
   143      make AWS_S3_BUCKET=beta-docs.docker.io BUILD_ROOT=yes docs-release
   144  
   145  Then go to http://beta-docs.docker.io.s3-website-us-west-2.amazonaws.com/
   146  to view your results and make sure what you published is what you wanted.
   147  
   148  When you're happy with it, publish the docs to our live site:
   149  
   150      make AWS_S3_BUCKET=docs.docker.com BUILD_ROOT=yes DISTRIBUTION_ID=C2K6......FL2F docs-release
   151  
   152  Test the uncached version of the live docs at http://docs.docker.com.s3-website-us-east-1.amazonaws.com/
   153      
   154  Note that the new docs will not appear live on the site until the cache (a complex,
   155  distributed CDN system) is flushed. The `make docs-release` command will do this
   156  _if_ the `DISTRIBUTION_ID` is set to the Cloudfront distribution ID (ask the meta
   157  team) - this will take at least 15 minutes to run and you can check its progress
   158  with the CDN Cloudfront Chrome addin.
   159