reformat for sphinx httpdoc

docs/conf.py

@@ -49,9 +49,9 @@ copyright = u'2014, The Addons Crew'
 # built documents.
 #
 # The short X.Y version.
-version = '0.8'
+version = '3.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.8'
+release = '3.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/topics/api/signing.rst

@@ -2,7 +2,7 @@
 Signing
 =======
 
-This API requires :doc:`authentication <auth>`.
+.. note:: This API requires :doc:`authentication <auth>`.
 
 -------------------
 Uploading a version
@@ -14,15 +14,33 @@ as multi-part formdata. This will create a pending version on the
 add-on and will prevent future submissions to this version unless
 validation or review fails.
 
-Example::
+If the upload succeeded then it will be submitted for
+validation and you will be able to check its status.
+
+.. http:put:: /en-US/firefox/api/v3/addons/[string:add-on-guid]/versions/[string:version]/
+
+    **Request:**
+
+    .. sourcecode:: bash
 
         curl https://addons.mozilla.org/en-US/firefox/api/v3/addons/my-addon/versions/1.0/
             -XPUT --form 'upload=@build/my-addon.xpi' -H 'Authorization: JWT <jwt-token>'
 
-The response will be the same as the :ref:`check-status` response.
+    :param addon-guid: the GUID for the add-on.
+    :param version: the version of the add-on.
+    :form upload: the add-on being uploaded.
+    :reqheader Content-Type: multipart/form-data
 
-If your upload has the right metadata then it will be submitted for
+    **Response:**
-validation and you will be able to check its status.
+
+    The response body will be the same as the :ref:`version-status` response.
+
+    :statuscode 201: new add-on and version created.
+    :statuscode 202: new version created.
+    :statuscode 400: an error occurred, check the `error` value in the JSON.
+    :statuscode 401: authentication failed.
+    :statuscode 403: you do not own this add-on.
+    :statuscode 409: version already exists.
 
 ------------------
 Creating an add-on
@@ -32,7 +50,7 @@ If this is the first time that your add-on's UUID has been seen then
 the add-on will be created as an unlisted add-on when the version is
 uploaded.
 
-.. _check-status:
+.. _version-status:
 
 -----------------------------------
 Checking the status of your upload
@@ -55,29 +73,53 @@ longer. Once review is complete then the ``reviewed`` property
 will be set and you can check the results with the ``passed_review``
 property.
 
-To make the request using curl::
+.. http:get:: /en-US/firefox/api/v3/addons/[string:add-on-guid]/versions/[string:version]/
+
+    **Request:**
+
+    .. sourcecode:: bash
 
         curl https://addons.mozilla.org/en-US/firefox/api/v3/addons/my-addon/versions/1.0/
             -H 'Authorization: JWT <jwt-token>'
 
-Here's a full example of a check status response::
+    :param addon-guid: the GUID for the add-on.
+    :param version: the version of the add-on.
+
+    **Response:**
+
+    .. code-block:: json
 
             {
                 "active": true,
                 "files": [
                     {
-                "download_url": "https://addons.mozilla.org/firefox/downloads/file/100/unlisted_wat-0.0.0-fx+an.xpi?src=api",
+                        "download_url": "https://addons.mozilla.org/firefox/downloads/file/100/unlisted_wat-1.0-fx+an.xpi?src=api",
                         "signed": true
                     }
                 ],
                 "passed_review": true,
                 "processed": true,
                 "reviewed": true,
-        "url": "https://addons.mozilla.org/en-US/firefox/api/v3/addons/%40new-unlisted-api/versions/0.0.0/",
+                "url": "https://addons.mozilla.org/en-US/firefox/api/v3/addons/%40new-unlisted-api/versions/1.0/",
                 "valid": true,
-        "validation_results": {
+                "validation_results": {},
-            ... snip ...
-        },
                 "validation_url": "https://addons.mozilla.org/en-US/developers/upload/f68abbb3b1624c098fe979a409fe3ce9",
-        "version": "0.0.0"
+                "version": "1.0"
             }
+
+    :>json active: version is active.
+    :>json files.download_url: URL to download the add-on file.
+    :>json files.signed: if the file is signed.
+    :>json passed_review: if the version has passed review.
+    :>json processed: if the version has been processed by the validator.
+    :>json reviewed: if the version has been reviewed.
+    :>json url: URL to this end point.
+    :>json valid: if the version passed validation.
+    :>json validation_results: the validation results (removed from the example for brevity).
+    :>json validation_url: a URL to the validation results in HTML format.
+    :>json version: the version.
+
+    :statuscode 200: request successful.
+    :statuscode 401: authentication failed.
+    :statuscode 403: you do not own this add-on.
+    :statuscode 404: add-on or version not found.

requirements/docs.txt

@@ -1,5 +1,5 @@
 # For buildings docs (also used by RTD)
-sphinxcontrib-httpdomain==1.1.9
+sphinxcontrib-httpdomain==1.4.0
 docutils==0.11
 Pygments==1.6
 Sphinx==1.2.2