Make docs build without warnings or errors. Minor additional cleanup.

docs/sources/api/docker_remote_api.rst

@@ -2,6 +2,9 @@
 :description: API Documentation for Docker
 :keywords: API, Docker, rcli, REST, documentation
 
+.. COMMENT use http://pythonhosted.org/sphinxcontrib-httpdomain/ to
+.. document the REST API.
+
 =================
 Docker Remote API
 =================
@@ -13,15 +16,23 @@ Docker Remote API
 
 - The Remote API is replacing rcli
 - Default port in the docker deamon is 4243 
-- The API tends to be REST, but for some complex commands, like attach or pull, the HTTP connection is hijacked to transport stdout stdin and stderr
+- The API tends to be REST, but for some complex commands, like attach
-- Since API version 1.2, the auth configuration is now handled client side, so the client has to send the authConfig as POST in /images/(name)/push
+  or pull, the HTTP connection is hijacked to transport stdout stdin
+  and stderr
+- Since API version 1.2, the auth configuration is now handled client
+  side, so the client has to send the authConfig as POST in
+  /images/(name)/push
 
 2. Versions
 ===========
 
 The current verson of the API is 1.3 
-Calling /images/<name>/insert is the same as calling /v1.3/images/<name>/insert
+
-You can still call an old version of the api using /v1.0/images/<name>/insert
+Calling /images/<name>/insert is the same as calling
+/v1.3/images/<name>/insert 
+
+You can still call an old version of the api using
+/v1.0/images/<name>/insert
 
 :doc:`docker_remote_api_v1.3`
 *****************************
@@ -29,19 +40,21 @@ You can still call an old version of the api using /v1.0/images/<name>/insert
 What's new
 ----------
 
-Listing processes (/top):
+.. http:get:: /containers/(id)/top
-
-- List the processes inside a container
 
+   **New!** List the processes running inside a container.
 
 Builder (/build):
 
 - Simplify the upload of the build context
-- Simply stream a tarball instead of multipart upload with 4 intermediary buffers
+- Simply stream a tarball instead of multipart upload with 4
+  intermediary buffers
 - Simpler, less memory usage, less disk usage and faster
 
-.. Note::
+.. Warning::
-The /build improvements are not reverse-compatible. Pre 1.3 clients will break on /build.
+
+  The /build improvements are not reverse-compatible. Pre 1.3 clients
+  will break on /build.
 
 List containers (/containers/json):
 
@@ -49,7 +62,8 @@ List containers (/containers/json):
 
 Start containers (/containers/<id>/start):
 
-- You can now pass host-specific configuration (e.g. bind mounts) in the POST body for start calls 
+- You can now pass host-specific configuration (e.g. bind mounts) in
+  the POST body for start calls
 
 :doc:`docker_remote_api_v1.2`
 *****************************
@@ -60,14 +74,25 @@ What's new
 ----------
 
 The auth configuration is now handled by the client.
-The client should send it's authConfig as POST on each call of /images/(name)/push
 
-.. http:get:: /auth is now deprecated
+The client should send it's authConfig as POST on each call of
-.. http:post:: /auth only checks the configuration but doesn't store it on the server
+/images/(name)/push
 
-Deleting an image is now improved, will only untag the image if it has chidrens and remove all the untagged parents if has any.
+.. http:get:: /auth 
 
-.. http:post:: /images/<name>/delete now returns a JSON with the list of images deleted/untagged
+  **Deprecated.**
+
+.. http:post:: /auth 
+
+  Only checks the configuration but doesn't store it on the server
+
+  Deleting an image is now improved, will only untag the image if it
+  has chidren and remove all the untagged parents if has any.
+
+.. http:post:: /images/<name>/delete 
+
+  Now returns a JSON structure with the list of images
+  deleted/untagged.
 
 
 :doc:`docker_remote_api_v1.1`
@@ -82,7 +107,7 @@ What's new
 .. http:post:: /images/(name)/insert
 .. http:post:: /images/(name)/push
 
-Uses json stream instead of HTML hijack, it looks like this:
+   Uses json stream instead of HTML hijack, it looks like this:
 
         .. sourcecode:: http
 

docs/sources/api/docker_remote_api_v1.0.rst

@@ -1,3 +1,8 @@
+.. use orphan to suppress "WARNING: document isn't included in any toctree"
+.. per http://sphinx-doc.org/markup/misc.html#file-wide-metadata
+
+:orphan:
+
 :title: Remote API v1.0
 :description: API Documentation for Docker
 :keywords: API, Docker, rcli, REST, documentation
@@ -300,8 +305,8 @@ Start a container
 	:statuscode 500: server error
 
 
-Stop a contaier
+Stop a container
-***************
+****************
 
 .. http:post:: /containers/(id)/stop
 

docs/sources/api/docker_remote_api_v1.1.rst

@@ -1,3 +1,7 @@
+.. use orphan to suppress "WARNING: document isn't included in any toctree"
+.. per http://sphinx-doc.org/markup/misc.html#file-wide-metadata
+
+:orphan:
 
 :title: Remote API v1.1
 :description: API Documentation for Docker

docs/sources/api/docker_remote_api_v1.2.rst

@@ -1,3 +1,8 @@
+.. use orphan to suppress "WARNING: document isn't included in any toctree"
+.. per http://sphinx-doc.org/markup/misc.html#file-wide-metadata
+
+:orphan:
+
 :title: Remote API v1.2
 :description: API Documentation for Docker
 :keywords: API, Docker, rcli, REST, documentation

docs/sources/api/docker_remote_api_v1.3.rst

@@ -1,3 +1,8 @@
+.. use orphan to suppress "WARNING: document isn't included in any toctree"
+.. per http://sphinx-doc.org/markup/misc.html#file-wide-metadata
+
+:orphan:
+
 :title: Remote API v1.3
 :description: API Documentation for Docker
 :keywords: API, Docker, rcli, REST, documentation

docs/sources/api/index_api.rst

@@ -452,7 +452,7 @@ User Register
          "username": "foobar"'}
 
     :jsonparameter email: valid email address, that needs to be confirmed
-    :jsonparameter username: min 4 character, max 30 characters, must match the regular expression [a-z0-9_].
+    :jsonparameter username: min 4 character, max 30 characters, must match the regular expression [a-z0-9\_].
     :jsonparameter password: min 5 characters
 
     **Example Response**:

docs/sources/api/registry_index_spec.rst

@@ -367,7 +367,8 @@ POST /v1/users
     {"email": "sam@dotcloud.com", "password": "toto42", "username": "foobar"'}
 
 **Validation**:
-    - **username** : min 4 character, max 30 characters, must match the regular expression [a-z0-9_].
+    - **username**: min 4 character, max 30 characters, must match the regular
+      expression [a-z0-9\_].
     - **password**: min 5 characters
 
 **Valid**: return HTTP 200

docs/sources/index.rst

@@ -2,8 +2,6 @@
 :description: An overview of the Docker Documentation
 :keywords: containers, lxc, concepts, explanation
 
-.. _introduction:
-
 Welcome
 =======
 

docs/sources/use/builder.rst

@@ -1,6 +1,6 @@
-:title: Dockerfile Builder
+:title: Dockerfiles for Images
-:description: Docker Builder specifes a simple DSL which allows you to automate the steps you would normally manually take to create an image.
+:description: Dockerfiles use a simple DSL which allows you to automate the steps you would normally manually take to create an image.
-:keywords: builder, docker, Docker Builder, automation, image creation
+:keywords: builder, docker, Dockerfile, automation, image creation
 
 ==================
 Dockerfile Builder
@@ -177,7 +177,7 @@ The copy obeys the following rules:
   with mode 0700, uid and gid 0.
 
 3.8 ENTRYPOINT
--------------
+--------------
 
     ``ENTRYPOINT /bin/echo``
 

docs/sources/use/workingwithrepository.rst

@@ -119,7 +119,7 @@ your container to an image within your username namespace.
 
 
 Pushing a container to its repository
-------------------------------------
+-------------------------------------
 
 In order to push an image to its repository you need to have committed
 your container to a named image (see above)