Use napoleon sphinx extension to parse Google-style docstrings

docs/api.rst

@@ -0,0 +1,5 @@
+API Reference
+=============
+
+.. automodule:: flask_micropub
+   :members:

docs/conf.py

@@ -32,6 +32,7 @@ import shlex
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -106,6 +107,21 @@ pygments_style = 'sphinx'
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# -- Napoleon docstrings
+
+
+# Napoleon settings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+
 
 # -- Options for HTML output ----------------------------------------------
 

docs/example.rst

@@ -0,0 +1,25 @@
+Example Usage
+=============
+
+.. code:: python
+
+    from flask import Flask, request, url_for
+    from flask.ext.micropub import MicropubClient
+
+    app = Flask(__name__)
+    micropub = MicropubClient(app)
+
+
+    @app.route('/login')
+    def login():
+        return micropub.authorize(
+            me, scope=request.args.get('scope'))
+
+
+    @app.route('/micropub-callback')
+    @micropub.authorized_handler
+    def micropub_callback(resp):
+        print('success!', resp.me, resp.access_token, resp.next_url, resp.error)
+
+See example.py for a more thorough example. Protocol details at
+https://indiewebcamp.com/IndieAuth and https://indiewebcamp.com/Micropub

docs/index.rst

@@ -3,65 +3,9 @@ Flask-Micropub
 
 A Flask extension to support IndieAuth and Micropub clients.
 
-Authentication
---------------
-
-Authentication uses the
-`IndieAuth <https://indiewebcamp.com/IndieAuth>`__ flow to confirm a
-user controls a particular URL, without requesting any sort of
-permissions or access token. Annotate an endpoint with
-``@micropub.authenticated_handler`` and then call
-``micropub.authenticate`` to initiate the login.
-
-Authorization
--------------
-
-Authorization uses the full
-`Micropub <https://indiewebcamp.com/Micropub>`__ flow to authenticate a
-user and then request an access token with which to make micropub
-requests. Annotate an endpoint with ``@micropub.authorized_handler`` and
-then call ``micropub.authorize`` to initiate the login.
-
-CSRF
-----
-
-MicropubClient provides a simple mechanism to deter Cross-Site Request
-Forgery. Based on `this Flask
-snippet <http://flask.pocoo.org/snippets/3/>`__, we generate a random
-string, pass it to the indieauth service via the state parameter, and
-then confirm we get the same random string back later.
-
-This helps prevent malicious sites from sending users to your indieauth
-endpoint against their will.
-
-Example
--------
-
-.. code:: python
-
-    from flask import Flask, request, url_for
-    from flask.ext.micropub import MicropubClient
-
-    app = Flask(__name__)
-    micropub = MicropubClient(app)
-
-
-    @app.route('/login')
-    def login():
-        return micropub.authorize(
-            me, scope=request.args.get('scope'))
-
-
-    @app.route('/micropub-callback')
-    @micropub.authorized_handler
-    def micropub_callback(resp):
-        print('success!', resp.me, resp.access_token, resp.next_url, resp.error)
-
-See example.py for a more thorough example. Protocol details at
-https://indiewebcamp.com/IndieAuth and https://indiewebcamp.com/Micropub
-
-API
----
-
-.. automodule:: flask_micropub
-   :members:
+.. toctree::
+   :maxdepth: 2
+   
+   intro
+   example
+   api

docs/intro.rst

@@ -0,0 +1,35 @@
+Flask-Micropub
+==============
+
+A Flask extension to support IndieAuth and Micropub clients.
+
+Authentication
+--------------
+
+Authentication uses the
+`IndieAuth <https://indiewebcamp.com/IndieAuth>`__ flow to confirm a
+user controls a particular URL, without requesting any sort of
+permissions or access token. Annotate an endpoint with
+``@micropub.authenticated_handler`` and then call
+``micropub.authenticate`` to initiate the login.
+
+Authorization
+-------------
+
+Authorization uses the full
+`Micropub <https://indiewebcamp.com/Micropub>`__ flow to authenticate a
+user and then request an access token with which to make micropub
+requests. Annotate an endpoint with ``@micropub.authorized_handler`` and
+then call ``micropub.authorize`` to initiate the login.
+
+CSRF
+----
+
+MicropubClient provides a simple mechanism to deter Cross-Site Request
+Forgery. Based on `this Flask
+snippet <http://flask.pocoo.org/snippets/3/>`__, we generate a random
+string, pass it to the indieauth service via the state parameter, and
+then confirm we get the same random string back later.
+
+This helps prevent malicious sites from sending users to your indieauth
+endpoint against their will.

flask_micropub.py

@@ -308,13 +308,9 @@ class AuthResponse:
     Attributes:
       me (string): The authenticated user's URL. This will be non-None if and
         only if the user was successfully authenticated.
-
       micropub_endpoint (string): The endpoint to POST micropub requests to.
-
       access_token (string): The authorized user's micropub access token.
-
       state (string): The optional state that was passed to authorize.
-
       error (string): describes the error encountered if any. It is possible
         that the authentication step will succeed but the access token step
         will fail, in which case me will be non-None, and error will describe