Fix #1919 document how to edit and release docs.

docs/README.md

@@ -1,38 +1,93 @@
 Docker Documentation
 ====================
 
-Documentation
+Overview
--------------
+--------
-This is your definite place to contribute to the docker documentation. After each push to master the documentation
-is automatically generated and made available on [docs.docker.io](http://docs.docker.io)
 
-Each of the .rst files under sources reflects a page on the documentation. 
+The source for Docker documentation is here under ``sources/`` in the
+form of .rst files. These files use
+[reStructuredText](http://docutils.sourceforge.net/rst.html)
+formatting with [Sphinx](http://sphinx-doc.org/) extensions for
+structure, cross-linking and indexing.
 
-Installation
+The HTML files are built and hosted on
-------------
+[readthedocs.org](https://readthedocs.org/projects/docker/), appearing
+via proxy on https://docs.docker.io. The HTML files 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" branch maps to the "master"
+documentation. 
+
+**Warning**: The "master" documentation may include features not yet
+part of any official docker release. "Master" docs should be used only
+for understanding bleeding-edge development and "latest" should be
+used for the latest official release.
+
+If you need to manually trigger a build of an existing branch, then
+you can do that through the [readthedocs
+interface](https://readthedocs.org/builds/docker/). If you would like
+to add new build targets, including new branches or tags, then you
+must contact one of the existing maintainers and get your
+readthedocs.org account added to the maintainers list, or just file an
+issue on GitHub describing the branch/tag and why it needs to be added
+to the docs, and one of the maintainers will add it for you.
+
+Getting Started
+---------------
+
+To edit and test the docs, you'll need to install the Sphinx tool and
+its dependencies. There are two main ways to install this tool:
+
+Native Installation
+...................
 
-* Work in your own fork of the code, we accept pull requests.
 * Install sphinx: `pip install sphinx`
-    * Mac OS X: `[sudo] pip-2.7 install sphinx`)
+    * Mac OS X: `[sudo] pip-2.7 install sphinx`
 * Install sphinx httpdomain contrib package: `pip install sphinxcontrib-httpdomain`
     * Mac OS X: `[sudo] pip-2.7 install sphinxcontrib-httpdomain`
 * If pip is not available you can probably install it using your favorite package manager as **python-pip**
 
+Alternative Installation: Docker Container
+..........................................
+
+If you're running ``docker`` on your development machine then you may
+find it easier and cleaner to use the Dockerfile. This installs Sphinx
+in a container, adds the local ``docs/`` directory and builds the HTML
+docs inside the container, even starting a simple HTTP server on port
+8000 so that you can connect and see your changes. Just run ``docker
+build .`` and run the resulting image. This is the equivalent to
+``make clean server`` since each container starts clean.
+
 Usage
 -----
-* Change the `.rst` files with your favorite editor to your liking.
+* Follow the contribution guidelines (``../CONTRIBUTING.md``)
-* Run `make docs` to clean up old files and generate new ones.
+* Work in your own fork of the code, we accept pull requests.
-* Your static website can now be found in the `_build` directory.
+* Change the ``.rst`` files with your favorite editor -- try to keep the
-* To preview what you have generated run `make server` and open http://localhost:8000/ in your favorite browser.
+  lines short and respect RST and Sphinx 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
 ----------------------------------
-Alternatively, for small changes and typo's you might want to use GitHub's built in file editor. It allows
+
-you to preview your changes right online. Just be careful not to create many commits.
+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 online (though there can be some differences between GitHub
+markdown and Sphinx RST). Just be careful not to create many commits.
 
 Images
 ------
-When you need to add images, try to make them as small as possible (e.g. as gif).
+
+When you need to add images, try to make them as small as possible
+(e.g. as gif). Usually images should go in the same directory as the
+.rst file which references them, or in a subdirectory if one already
+exists.
 
 Notes
 -----
@@ -41,7 +96,7 @@ lessc ``lessc main.less`` or watched using watch-lessc ``watch-lessc -i main.les
 
 Guides on using sphinx
 ----------------------
-* To make links to certain pages create a link target like so:
+* To make links to certain sections create a link target like so:
 
   ```
     .. _hello_world:
@@ -52,7 +107,10 @@ Guides on using sphinx
     This is.. (etc.)
   ```
 
-  The ``_hello_world:`` will make it possible to link to this position (page and marker) from all other pages.
+  The ``_hello_world:`` will make it possible to link to this position
+  (page and section heading) from all other pages. See the [Sphinx
+  docs](http://sphinx-doc.org/markup/inline.html#role-ref) for more
+  information and examples.
 
 * Notes, warnings and alarms
 
@@ -68,13 +126,17 @@ Guides on using sphinx
 
 * Code examples
 
-  Start without $, so it's easy to copy and paste.
+  * Start without $, so it's easy to copy and paste.
+  * Use "sudo" with docker to ensure that your command is runnable
+    even if they haven't [used the *docker*
+    group](http://docs.docker.io/en/latest/use/basics/#why-sudo).
 
 Manpages
 --------
 
-* To make the manpages, simply run 'make man'. Please note there is a bug in spinx 1.1.3 which makes this fail.
+* To make the manpages, run ``make man``. Please note there is a bug
-Upgrade to the latest version of sphinx.
+  in spinx 1.1.3 which makes this fail.  Upgrade to the latest version
-* Then preview the manpage by running `man _build/man/docker.1`, where _build/man/docker.1 is the path to the generated
+  of Sphinx.
-manfile
+* Then preview the manpage by running ``man _build/man/docker.1``,
-* The manpages are also autogenerated by our hosted readthedocs here: http://docs-docker.dotcloud.com/projects/docker/downloads/
+  where ``_build/man/docker.1`` is the path to the generated manfile
+