Clean up sphinx syntax, upgrade http markup package, minor link changes, update intro.

docs/requirements.txt

@@ -1,2 +1,2 @@
 Sphinx==1.1.3
-sphinxcontrib-httpdomain==1.1.8
+sphinxcontrib-httpdomain==1.1.9

docs/sources/api/docker_remote_api_v1.7.rst

@@ -13,9 +13,12 @@ Docker Remote API v1.7
 1. Brief introduction
 =====================
 
-- The Remote API is replacing rcli
+- The Remote API has replaced rcli
-- Default port in the docker daemon is 4243
+- The daemon listens on ``unix:///var/run/docker.sock``, but you can
-- 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
+  :ref:`bind_docker`.
+- 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``
 
 2. Endpoints
 ============
@@ -690,10 +693,12 @@ Create an image
         :query repo: repository
 	:query tag: tag
 	:query registry: the registry to pull from
+	:reqheader X-Registry-Auth: base64-encoded AuthConfig object
         :statuscode 200: no error
         :statuscode 500: server error
 
 
+
 Insert a file in an image
 *************************
 
@@ -835,18 +840,16 @@ Push an image on the registry
     HTTP/1.1 200 OK
     Content-Type: application/json
 
-   {"status":"Pushing..."}
+    {"status":"Pushing..."}
-   {"status":"Pushing", "progress":"1/? (n/a)"}
+    {"status":"Pushing", "progress":"1/? (n/a)"}
-   {"error":"Invalid..."}
+    {"error":"Invalid..."}
-   ...
+    ...
-
-	The ``X-Registry-Auth`` header can be used to include a
-	base64-encoded AuthConfig object.
 
    :query registry: the registry you wan to push, optional
+   :reqheader X-Registry-Auth: include a base64-encoded AuthConfig object.
    :statuscode 200: no error
-        :statuscode 404: no such image
+   :statuscode 404: no such image
-        :statuscode 500: server error
+   :statuscode 500: server error
 
 
 Tag an image into a repository
@@ -959,9 +962,9 @@ Search images
 	   ...
 	   ]
 
-	   :query term: term to search
+	:query term: term to search
-	   :statuscode 200: no error
+	:statuscode 200: no error
-	   :statuscode 500: server error
+	:statuscode 500: server error
 
 
 2.3 Misc
@@ -991,18 +994,22 @@ Build an image from Dockerfile via stdin
       {{ STREAM }}
 
 
-       The stream must be a tar archive compressed with one of the following algorithms:
+   The stream must be a tar archive compressed with one of the
-       identity (no compression), gzip, bzip2, xz. The archive must include a file called
+   following algorithms: identity (no compression), gzip, bzip2,
-       `Dockerfile` at its root. It may include any number of other files, which will be
+   xz. 
-       accessible in the build context (See the ADD build command).
 
-       The Content-type header should be set to "application/tar".
+   The archive must include a file called ``Dockerfile`` at its
+   root. It may include any number of other files, which will be
+   accessible in the build context (See the :ref:`ADD build command
+   <dockerbuilder>`).
+
+   :query t: repository name (and optionally a tag) to be applied to the resulting image in case of success
+   :query q: suppress verbose build output
+   :query nocache: do not use the cache when building the image
+   :reqheader Content-type: should be set to ``"application/tar"``.
+   :statuscode 200: no error
+   :statuscode 500: server error
 
-	:query t: repository name (and optionally a tag) to be applied to the resulting image in case of success
-	:query q: suppress verbose build output
-    :query nocache: do not use the cache when building the image
-	:statuscode 200: no error
-    :statuscode 500: server error
 
 
 Check auth configuration

docs/sources/use/basics.rst

@@ -34,13 +34,11 @@ This will find the ``ubuntu`` image by name in the :ref:`Central Index
 <searching_central_index>` and download it from the top-level Central 
 Repository to a local image cache.
 
-.. NOTE:: When the image has successfully downloaded, you will see a 12 
+.. NOTE:: When the image has successfully downloaded, you will see a
-character hash ``539c0211cd76: Download complete`` which is the short 
+   12 character hash ``539c0211cd76: Download complete`` which is the
-form of the image ID. These short image IDs are the first 12 characters 
+   short form of the image ID. These short image IDs are the first 12
-of the full image ID - which can be found using ``docker inspect`` or 
+   characters of the full image ID - which can be found using ``docker
-``docker images -notrunc=true``
+   inspect`` or ``docker images -notrunc=true``
-
-.. _dockergroup:
 
 Running an interactive shell
 ----------------------------
@@ -53,6 +51,7 @@ Running an interactive shell
   # use the escape sequence Ctrl-p + Ctrl-q
   sudo docker run -i -t ubuntu /bin/bash
 
+.. _dockergroup:
 
 Why ``sudo``?
 -------------
@@ -87,7 +86,7 @@ you don't need to add ``sudo`` to all the client commands.
 Bind Docker to another host/port or a Unix socket
 -------------------------------------------------
 
-.. DANGER:: Changing the default ``docker`` daemon binding to a TCP
+.. warning:: Changing the default ``docker`` daemon binding to a TCP
    port or Unix *docker* user group will increase your security risks
    by allowing non-root users to potentially gain *root* access on the
    host (`e.g. #1369