Use napoleon sphinx extension to parse Google-style docstrings

This commit is contained in:
Kyle Mahan 2015-12-16 18:28:29 +00:00
parent 6677bcd138
commit d9a5ff9099
6 changed files with 87 additions and 66 deletions

5
docs/api.rst Normal file
View File

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

View File

@ -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 ----------------------------------------------

25
docs/example.rst Normal file
View File

@ -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

View File

@ -3,65 +3,9 @@ Flask-Micropub
A Flask extension to support IndieAuth and Micropub clients.
Authentication
--------------
.. toctree::
:maxdepth: 2
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:
intro
example
api

35
docs/intro.rst Normal file
View File

@ -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.

View File

@ -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