mostly updating documentation

doc/client/index.rst

@@ -67,9 +67,9 @@ All URLs must end with "/"; if you forget to add them in the URL, you'll
 receive a redirect to the path with "/".
 
 API
-----
+====
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    users_and_tokens

doc/client/users_and_tokens.rst

@@ -10,7 +10,7 @@ should use this request to get a valid token:
 
 .. autoflask:: luncho.server:app
    :blueprints: token
-   :undoc-endpoints: static
+   :undoc-endpoints: static,show_api
 
 
 Users
@@ -18,4 +18,4 @@ Users
 
 .. autoflask:: luncho.server:app
    :blueprints: users
-   :undoc-endpoints: static
+   :undoc-endpoints: static,show_api

doc/conf.py

@@ -15,11 +15,12 @@
 import sys
 import os
 
+import sphinx_readable_theme
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('..'))
-sys.path.append(os.path.abspath('_themes/flask-sphinx-themes'))
 
 # -- General configuration ------------------------------------------------
 
@@ -105,7 +106,7 @@ pygments_style = 'sphinx'
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #html_theme = 'default'
-html_theme = 'flask'
+html_theme = 'readable'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -113,7 +114,7 @@ html_theme = 'flask'
 #html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ['_themes/flask-sphinx-themes/']
+html_theme_path = [sphinx_readable_theme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".

luncho/blueprints/token.py

@@ -19,7 +19,15 @@ from luncho.exceptions import LunchoException
 # ----------------------------------------------------------------------
 
 class UserDoesNotExistException(LunchoException):
-    """There is no such user in the database."""
+    """There is no such user in the database.
+
+    .. sourcecode:: http
+
+       HTTP/1.1 404 Not found
+       Content-Type: text/json
+
+       { "status": "ERROR", "message": "User does not exist" }
+    """
     def __init__(self):
         super(UserDoesNotExistException, self).__init__()
         self.status = 404
@@ -27,7 +35,15 @@ class UserDoesNotExistException(LunchoException):
 
 
 class InvalidPasswordException(LunchoException):
-    """Invalid password."""
+    """Invalid password.
+
+    .. sourcecode:: http
+
+       HTTP/1.1 401 Unauthorized
+       Content-Type: text/json
+
+       { "status": "ERROR", "message": "Invalid password" }
+    """
     def __init__(self):
         super(InvalidPasswordException, self).__init__()
         self.status = 401
@@ -62,23 +78,9 @@ def get_token():
 
        { "status": "OK", "token": "access_token" }
 
-    **Invalid password (401)**:
-
-    .. sourcecode:: http
-
-       HTTP/1.1 401 Unauthorized
-       Content-Type: text/json
-
-       { "status": "ERROR", "message": "Invalid password" }
+    **Invalid password (401)**: :py:class:`InvalidPasswordException`
 
-    **Unknown user (404)**:
-
-    .. sourcecode:: http
-
-       HTTP/1.1 404 Not found
-       Content-Type: text/json
-
-       { "status": "ERROR", "message": "User does not exist" }
+    **Unknown user (404)**: :py:class:`UserDoesNotExistException`
     """
     json = request.get_json(force=True)
 

luncho/helpers.py

@@ -46,6 +46,11 @@ class ForceJSON(object):
 
 
 def auth(func):
+    """Decorator to make the request authenticated via token. If the token
+    is missing or it is invalid, the decorator will raise the proper
+    exceptions (and return the proper error codes). If the token is valid,
+    a "user" property will be added to the request object with the current
+    user."""
     @wraps(func)
     def check_auth(*args, **kwargs):
         if not request.authorization:

requirements-dev.txt

@@ -2,3 +2,4 @@ nose
 nosexcover
 sphinx
 sphinxcontrib-httpdomain
+sphinx-readable-theme