diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..55f8210 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,5 @@ +API Reference +============= + +.. automodule:: flask_micropub + :members: diff --git a/docs/conf.py b/docs/conf.py index 0259107..b8fdaef 100644 --- a/docs/conf.py +++ b/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 ---------------------------------------------- diff --git a/docs/example.rst b/docs/example.rst new file mode 100644 index 0000000..1ad9653 --- /dev/null +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index c7d14ec..9802d2e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,65 +3,9 @@ Flask-Micropub A Flask extension to support IndieAuth and Micropub clients. -Authentication --------------- - -Authentication uses the -`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 `__ 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 `__, 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 diff --git a/docs/intro.rst b/docs/intro.rst new file mode 100644 index 0000000..f6a9a24 --- /dev/null +++ b/docs/intro.rst @@ -0,0 +1,35 @@ +Flask-Micropub +============== + +A Flask extension to support IndieAuth and Micropub clients. + +Authentication +-------------- + +Authentication uses the +`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 `__ 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 `__, 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. diff --git a/flask_micropub.py b/flask_micropub.py index 9f689d8..37bcade 100644 --- a/flask_micropub.py +++ b/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