From 7744f63159cee9cfa5d9e9307e5c29a4f589837f Mon Sep 17 00:00:00 2001 From: James Turnbull Date: Sat, 26 Apr 2014 08:10:19 -0400 Subject: [PATCH] Updated Docs README Docker-DCO-1.1-Signed-off-by: James Turnbull (github: jamtur01) --- docs/README.md | 74 ++++++++++++++++++++++++-------------------------- 1 file changed, 35 insertions(+), 39 deletions(-) diff --git a/docs/README.md b/docs/README.md index a113cb9edd..e5474d524d 100755 --- a/docs/README.md +++ b/docs/README.md @@ -7,64 +7,60 @@ Overview The source for Docker documentation is here under ``sources/`` and uses extended Markdown, as implemented by [mkdocs](http://mkdocs.org). -The HTML files are built and hosted on https://docs.docker.io, and update -automatically after each change to the master or release branch of the -[docker files on GitHub](https://github.com/dotcloud/docker) thanks to -post-commit hooks. The "release" branch maps to the "latest" -documentation and the "master" (unreleased development) branch maps to the "master" -documentation. +The HTML files are built and hosted on `https://docs.docker.io`, and +update automatically after each change to the master or release branch +of [Docker on GitHub](https://github.com/dotcloud/docker) +thanks to post-commit hooks. The "docs" branch maps to the "latest" +documentation and the "master" (unreleased development) branch maps to +the "master" documentation. ## Branches **There are two branches related to editing docs**: ``master`` and a -``docs`` branch. You should always edit -docs 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. +``docs`` branch. You should always edit documentation on a local branch +of the ``master`` branch, and send a PR against ``master``. -Now that we have a ``docs`` branch, we can keep the [http://docs.docker.io](http://docs.docker.io) docs -up to date with any bugs found between ``docker`` code releases. +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. -**Warning**: When *reading* the docs, the [http://beta-docs.docker.io](http://beta-docs.docker.io) documentation may -include features not yet part of any official docker -release. The ``beta-docs`` site should be used only for understanding -bleeding-edge development and ``docs.docker.io`` (which points to the ``docs`` +Also, now that we have a ``docs`` branch, we can keep the +[http://docs.docker.io](http://docs.docker.io) docs up to date with any +bugs found between ``docker`` code releases. + +**Warning**: When *reading* the docs, the +[http://beta-docs.docker.io](http://beta-docs.docker.io) documentation +may include features not yet part of any official docker release. The +``beta-docs`` site should be used only for understanding bleeding-edge +development and ``docs.docker.io`` (which points to the ``docs`` branch``) should be used for the latest official release. 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. +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 ``docker`` source directory, run: - ```make docs``` +In the root of the ``docker`` source directory: + + cd docker + +Run: + + make docs If you have any issues you need to debug, you can use ``make docs-shell`` and then run ``mkdocs serve`` # Contributing -## Normal Case: - * Follow the contribution guidelines ([see ``../CONTRIBUTING.md``](../CONTRIBUTING.md)). * [Remember to sign your work!](../CONTRIBUTING.md#sign-your-work) -* Work in your own fork of the code, we accept pull requests. -* Change the ``.md`` files with your favorite editor -- try to keep the - lines short (80 chars) and respect Markdown conventions. -* Run ``make clean docs`` to clean up old files and generate new ones, - or just ``make docs`` to update after small changes. -* Your static website can now be found in the ``_build`` directory. -* To preview what you have generated run ``make server`` and open - http://localhost:8000/ in your favorite browser. - -``make clean docs`` must complete without any warnings or errors. Working using GitHub's file editor ---------------------------------- @@ -87,7 +83,7 @@ Publishing Documentation ------------------------ To publish a copy of the documentation you need a ``docs/awsconfig`` -file containing AWS settings to deploy to. The release script will +file containing AWS settings to deploy to. The release script will create an s3 if needed, and will then push the files to it. ``` @@ -97,7 +93,7 @@ aws_secret_access_key = OIUYSADJHLKUHQWIUHE...... region = ap-southeast-2 ``` -The ``profile`` name must be the same as the name of the bucket you are +The ``profile`` name must be the same as the name of the bucket you are deploying to - which you call from the docker directory: ``make AWS_S3_BUCKET=dowideit-docs docs-release``