Docs done for now. Releasing v0.1.0.

Author: Perlkonig

docs/examples.rst

@@ -0,0 +1,36 @@
+Examples
+========
+
+The library is pretty thoroughly unit tested. See the ``tests`` folder for those.
+
+Here are very basic examples.
+
+Step 1: Generate a URL::
+
+    import sqrlserver
+    import nacl.utils
+
+    key = nacl.utils.random(32)
+    url = sqrlserver.Url('example.com', 'Example Site')
+    urlstr = u.generate('/auth/sqrl')
+    #urlstr = 'sqrl://example.com/auth/sqrl?nut=XXXXX&sfn=RXhhbXBsZSBTaXRl'
+
+Step 2: Receive a Request::
+
+    req = Request(key, postparams) #let's assume a basic ``query`` command
+    assert req.state == 'NEW'
+
+Step 3: Handle the Request::
+
+    req.handle()
+    assert req.state == 'ACTION'
+    assert req.action == [('find', ['TLpyrowLhWf9-hdLLPQOA-7-xplI9LOxsfLXsyTccVc'])]
+
+    req.handle({'found': [True]})
+    assert req.state == 'COMPLETE'
+
+Step 4: Finalize & Return the Response::
+
+    response = req.finalize(counter=101) #will use last URL for 'qry'
+    #store ``response.hmac(key)`` to the session data
+    #return ``response.toString()`` to the client

docs/index.rst

@@ -12,10 +12,11 @@ SQRL Server
    :hidden:
 
    usage
+   examples
    divergences
    API <modules>
 
-This module supports Python-based web servers in processing `SQRL <https://www.grc.com/sqrl/sqrl.htm>`_ requests. It only does the core protocol work. It leaves data representation, storage, and other platform-specific actions to the server.
+This module supports Python-based web servers in processing `SQRL <https://www.grc.com/sqrl/sqrl.htm>`_ requests. It only does the core protocol work (signature validation, etc.). It leaves data representation, storage, and other platform-specific actions to the server.
 
 The following terms are used throughout the documentation:
 
@@ -43,6 +44,14 @@ For now, download and install manually::
     python setup.py test
     python setup.py install
 
+Requirements
+============
+
+This library only works with Python3. It requires the following external libraries to run:
+
+- bitstring
+- PyNaCl
+
 Contribute
 ==========
 
@@ -54,6 +63,11 @@ Licence
 
 The project is licensed under the MIT licence.
 
+Changelog
+=========
+
+01 Jul 2017
+  * Initial release (v0.1.0)
 
 Indices and tables
 ==================

docs/usage.rst

@@ -9,8 +9,7 @@ The core workflow is quite simple:
 #. Create a :py:class:`.Url` to generate the URLs that point clients to your SQRL endpoints.
 #. Create a :py:class:`.Request` object when a POST is made to those endpoints.
 #. Call the request's :py:meth:`.Request.handle` method repeatedly until its ``state`` is ``COMPLETE``.
-#. Call :py:meth:`.Request.finalize` to get a :py:class:`.Response` object.
-#. Return :py:meth:`.Response.toString` to the client.
+#. Call :py:meth:`.Request.finalize` to get a :py:class:`.Response` object and then return :py:meth:`.Response.toString` to the client.
 
 Step 1: Generate a URL
 ----------------------
@@ -353,17 +352,14 @@ encrypted values.
 
 The value must be a string.
 
-Step 4: Finalize the Request
-----------------------------
+Step 4: Finalize & Return the Response
+--------------------------------------
 
 The :py:meth:`.Request.finalize` method does the final steps to prepare the :py:class:`.Response`. You must pass it either a :py:class:`.Nut` you manually generated or the data needed to autogenerate a new one for you. It also finalizes the URL you want the client to respond to with its next request.
 
 This method does not affect the :py:class:`.Request` object in any way. You can safely call this method multiple times with different parameters.
 
-it will return to you a valid :py:class:`.Response` object.
-
-Step 5: Return the Response
----------------------------
+It will return to you a valid :py:class:`.Response` object.
 
 At this point it's a simple matter of calling :py:meth:`.Response.toString` and returning that in the body of your response to the client's POST.