From 09d4b9452d80b70bf4d510891cf3545b3350cdf2 Mon Sep 17 00:00:00 2001
From: Ken Cochrane <KenCochrane@gmail.com>
Date: Mon, 6 May 2013 13:38:51 -0400
Subject: [PATCH] added new sphinx contrib extention for better REST API docs,
 and changed the index search API so that it uses the new docs, as a test to
 make sure it works correctly

---
 docs/requirements.txt              |  2 ++
 docs/sources/commandline/index.rst |  2 +-
 docs/sources/conf.py               |  2 +-
 docs/sources/index/search.rst      | 38 ++++++++++++++++++++++--------
 docs/sources/registry/api.rst      |  6 ++++-
 5 files changed, 37 insertions(+), 13 deletions(-)
 create mode 100644 docs/requirements.txt

diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000000000000000000000000000000000000..9d1ce18f5c2168b277d2279c0ae5689b02c8c6b3
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,2 @@
+Sphinx==1.1.3
+sphinxcontrib-httpdomain==1.1.8
\ No newline at end of file
diff --git a/docs/sources/commandline/index.rst b/docs/sources/commandline/index.rst
index d5ea959f6eab640e2eb7ac338bfe93f8434328bb..d19d39ab60f16cef620410ee74c9d8de142d7a6f 100644
--- a/docs/sources/commandline/index.rst
+++ b/docs/sources/commandline/index.rst
@@ -9,7 +9,7 @@ Commands
 Contents:
 
 .. toctree::
-  :maxdepth: 2
+  :maxdepth: 3
 
   basics
   workingwithrepository
diff --git a/docs/sources/conf.py b/docs/sources/conf.py
index c05c7d10a45ab650829ea6d31a53752062c87990..4c54d8bb62e62a55c0425cbce044d2e3e9a3489f 100644
--- a/docs/sources/conf.py
+++ b/docs/sources/conf.py
@@ -25,7 +25,7 @@ import sys, os
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = ['sphinxcontrib.httpdomain']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
diff --git a/docs/sources/index/search.rst b/docs/sources/index/search.rst
index 0c7624de72aca3ec67a359fb89d7ed53a5b8e5b7..498295fa2b29451122b2f94cd6ad59d47a8bfab0 100644
--- a/docs/sources/index/search.rst
+++ b/docs/sources/index/search.rst
@@ -5,16 +5,34 @@ Docker Index Search API
 Search
 ------
 
-**URL:** /v1/search?q={{search_term}}
+.. http:get:: /v1/search
 
-**Results:**
+   Search the Index given a search term. It accepts :http:method:`get` only.
 
-.. code-block:: json
+   **Example request**:
 
-   {"query":"{{search_term}}",
-    "num_results": 27,
-    "results" : [
-       {"name": "dotcloud/base", "description": "A base ubuntu64  image..."},
-       {"name": "base2", "description": "A base ubuntu64  image..."},
-     ]
-   }
\ No newline at end of file
+   .. sourcecode:: http
+
+      GET /v1/search?q=search_term HTTP/1.1
+      Host: example.com
+      Accept: application/json
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Vary: Accept
+      Content-Type: application/json
+
+      {"query":"search_term",
+        "num_results": 2,
+        "results" : [
+           {"name": "dotcloud/base", "description": "A base ubuntu64  image..."},
+           {"name": "base2", "description": "A base ubuntu64  image..."},
+         ]
+       }
+   
+   :query q: what you want to search for
+   :statuscode 200: no error
+   :statuscode 500: server error
\ No newline at end of file
diff --git a/docs/sources/registry/api.rst b/docs/sources/registry/api.rst
index 1cca9fb24406046de0d9dfee32f62e4d35f0e081..ec2591af4c9d7a33b97edf0220298bf52273278b 100644
--- a/docs/sources/registry/api.rst
+++ b/docs/sources/registry/api.rst
@@ -84,7 +84,9 @@ It’s possible to run docker pull https://<registry>/repositories/samalba/busyb
 
 Currently registry redirects to s3 urls for downloads, going forward all downloads need to be streamed through the registry. The Registry will then abstract the calls to S3 by a top-level class which implements sub-classes for S3 and local storage.
 
-Token is only returned when it is a private repo, public repos do not require tokens to be returned. The Registry will still contact the Index to make sure the pull is authorized (“is it ok to download this repos without a Token?”).
+Token is only returned when the 'X-Docker-Token' header is sent with request.
+
+Basic Auth is required to pull private repos. Basic auth isn't required for pulling public repos, but if one is provided, it needs to be valid and for an active account.
 
 API (pulling repository foo/bar):
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -426,6 +428,8 @@ You have 3 options:
         - X-Docker-Token: true
 
     In this case, along with the 200 response, you’ll get a new token (if user auth is ok):
+    If authorization isn't correct you get a 401 response.
+    If account isn't active you will get a 403 response.
 
     **Response**:
         - 200 OK