docs: auto generate authorization header in api doc

Makefile

@@ -10,6 +10,9 @@ test:
 	make unit
 	make e2e
 
+docs:
+	make -C docs html
+
 e2e:
 	py.test -vv ./test/e2etest.py
 
@@ -36,4 +39,4 @@ combined-cov:
 	coverage combine
 	coverage report -m
 
-.PHONY: test
+.PHONY: test docs

Procfile

@@ -1,2 +1,3 @@
 web: make serve
 sender: make sender
+doc: cd docs/build/html && python -m SimpleHTTPServer 16647

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+SPHINXBUILD   = sphinx-build -E
 PAPER         =
 BUILDDIR      = build
 

docs/source/rest_api.rst

@@ -1,22 +1,25 @@
 REST API
 ========
 
+.. _hmac-auth-label:
+
 HMAC Auth
 ---------
 
-API requests which require auth will have an extra :code:`AUTHORIZATION` HTTP header. It looks like
-this:
+API requests which require API key auth will have an extra
+:code:`AUTHORIZATION` HTTP header. It looks like this:
 
 .. code-block:: none
 
   AUTHORIZATION: hmac $application:$payload
 
-:code:`$payload` is a base64 encoded hmac sha512 digest of the following string. In the resulting base64 string, instances of :code:`+` are replaced with :code:`-`
-and :code:`/` are replaced with :code:`_`.
+:code:`$payload` is a base64 encoded hmac sha512 digest of the following string
+with the app's API key. In the resulting base64 string, instances of :code:`+`
+are replaced with :code:`-` and :code:`/` are replaced with :code:`_`.
 
 .. code-block:: none
 
-  $window $httpMethod $path $body
+  HMAC($api_key, "$window $httpMethod $path $body")
 
 :code:`$window` is the current unix timestamp in seconds, divided by 5, floor'd.
 

src/iris/sphinx_extension.py

@@ -56,6 +56,9 @@ def make_rst(self, section_title_set):
                 continue
             if not docstring:
                 continue
+            if not (handler.__self__.allow_read_no_auth and method == 'GET'):
+                docstring += '\n:reqheader Authorization: see :ref:`hmac-auth-label`.\n'
+
             docstring = prepare_docstring(docstring)
 
             # generate section title if needed