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,16 +14,34 @@ 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::
-
-    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.
-
-If your upload has the right metadata then it will be submitted for
+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>'
+
+    :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
+
+    **Response:**
+
+    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]/
 
-    curl https://addons.mozilla.org/en-US/firefox/api/v3/addons/my-addon/versions/1.0/
-         -H 'Authorization: JWT <jwt-token>'
+    **Request:**
 
-Here's a full example of a check status response::
+    .. sourcecode:: bash
+
+        curl https://addons.mozilla.org/en-US/firefox/api/v3/addons/my-addon/versions/1.0/
+            -H 'Authorization: JWT <jwt-token>'
+
+    :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",
-                "signed": true
+                "active": true,
+                "files": [
+                    {
+                        "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/1.0/",
+                "valid": true,
+                "validation_results": {},
+                "validation_url": "https://addons.mozilla.org/en-US/developers/upload/f68abbb3b1624c098fe979a409fe3ce9",
+                "version": "1.0"
             }
-        ],
-        "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/",
-        "valid": true,
-        "validation_results": {
-            ... snip ...
-        },
-        "validation_url": "https://addons.mozilla.org/en-US/developers/upload/f68abbb3b1624c098fe979a409fe3ce9",
-        "version": "0.0.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