Initial work for API documentation.

The sphinx config stuff should be basically done at this point. All the
actual docstrings for the API need some extra love, I'll try to get
those updated and up to snuff soon.

Author: vimalloc

docs/api.rst

@@ -0,0 +1,50 @@
+API Documentation
+=================
+.. currentmodule:: flask_jwt_extended
+
+.. module:: flask_jwt_extended
+
+.. autoclass:: JWTManager
+
+  .. automethod:: __init__
+  .. automethod:: init_app
+  .. automethod:: user_claims_loader
+  .. automethod:: user_identity_loader
+  .. automethod:: expired_token_loader
+  .. automethod:: invalid_token_loader
+  .. automethod:: unauthorized_loader
+  .. automethod:: needs_fresh_token_loader
+  .. automethod:: revoked_token_loader
+  .. automethod:: user_loader_callback_loader
+  .. automethod:: user_loader_error_loader
+  .. automethod:: token_in_blacklist_loader
+  .. automethod:: claims_verification_loader
+  .. automethod:: claims_verification_failed_loader
+
+
+Protected endpiont decorators
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. autofunction:: jwt_required
+.. autofunction:: jwt_refresh_token_required
+.. autofunction:: fresh_jwt_required
+.. autofunction:: jwt_optional
+
+
+Utilities
+~~~~~~~~~
+.. autofunction:: create_access_token
+.. autofunction:: create_refresh_token
+
+.. attribute:: current_user
+
+  A LocalProxy for accessing the current user. Roughly equilivant to `get_current_user()`
+
+.. autofunction:: decode_token
+.. autofunction:: get_current_user
+.. autofunction:: get_jti
+.. autofunction:: get_jwt_claims
+.. autofunction:: get_jwt_identity
+.. autofunction:: get_raw_jwt
+.. autofunction:: set_access_cookies
+.. autofunction:: set_refresh_cookies
+.. autofunction:: unset_jwt_cookies

docs/conf.py

@@ -20,6 +20,7 @@
 
 
 sys.path.insert(0, os.path.abspath('../../..'))
+sys.path.insert(0, os.path.abspath('..'))
 sys.path.insert(0, os.path.abspath('../flask_jwt_extended/'))
 sys.path.append(os.path.join(os.path.dirname(__file__), '_themes'))
 
@@ -57,17 +58,16 @@
 
 # General information about the project.
 project = u'flask-jwt-extended'
-copyright = u'2016, Landon Gilbert-Bland, rlam3'
-author = u'Landon Gilbert-Bland, rlam3'
+author = u'Landon Gilbert-Bland'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u'0.0.2'
+version = u'3.2.0'
 # The full version, including alpha/beta/rc tags.
-release = u'0.0.2'
+release = u'3.2.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -162,7 +162,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/index.rst

@@ -6,8 +6,7 @@
 Flask JWT Extended's documentation
 ==================================
 
-In here you will find examples of how to use Flask JWT Extended. Full API
-documentation is coming soon!
+In here you will find examples of how to use Flask JWT Extended.
 
 .. toctree::
    :maxdepth: 2
@@ -23,3 +22,4 @@ documentation is coming soon!
    options
    blacklist_and_token_revoking
    tokens_in_cookies
+   api

flask_jwt_extended/jwt_manager.py

@@ -23,6 +23,13 @@
 
 
 class JWTManager(object):
+    """
+    This object is used to hold the JWT settings and callback functions.
+    Instances :class:`JWTManager` are *not* bound to specific apps, so
+    you can create one in the main body of your code and then bind it
+    to your app in a factory function.
+    """
+
     def __init__(self, app=None):
         """
         Create the JWTManager instance. You can either pass a flask application
@@ -330,23 +337,7 @@ def claims_verification_failed_loader(self, callback):
         self._claims_verification_failed_callback = callback
         return callback
 
-    def create_refresh_token(self, identity, expires_delta=None):
-        """
-        Creates a new refresh token
-
-        :param identity: The identity of this token. This can be any data that is
-                         json serializable. It can also be an object, in which case
-                         you can use the user_identity_loader to define a function
-                         that will be called to pull a json serializable identity
-                         out of this object. This is useful so you don't need to
-                         query disk twice, once for initially finding the identity
-                         in your login endpoint, and once for setting addition data
-                         in the JWT via the user_claims_loader
-        :param expires_delta: A datetime.timedelta for how long this token should
-                              last before it expires. If this is None, it will
-                              use the 'JWT_REFRESH_TOKEN_EXPIRES` config value
-        :return: A new refresh token
-        """
+    def _create_refresh_token(self, identity, expires_delta=None):
         if expires_delta is None:
             expires_delta = config.refresh_expires
 
@@ -360,25 +351,7 @@ def create_refresh_token(self, identity, expires_delta=None):
         )
         return refresh_token
 
-    def create_access_token(self, identity, fresh=False, expires_delta=None):
-        """
-        Creates a new access token
-
-        :param identity: The identity of this token. This can be any data that is
-                         json serializable. It can also be an object, in which case
-                         you can use the user_identity_loader to define a function
-                         that will be called to pull a json serializable identity
-                         out of this object. This is useful so you don't need to
-                         query disk twice, once for initially finding the identity
-                         in your login endpoint, and once for setting addition data
-                         in the JWT via the user_claims_loader
-        :param fresh: If this token should be marked as fresh, and can thus access
-                      fresh_jwt_required protected endpoints. Defaults to False
-        :param expires_delta: A datetime.timedelta for how long this token should
-                              last before it expires. If this is None, it will
-                              use the 'JWT_ACCESS_TOKEN_EXPIRES` config value
-        :return: A new access token
-        """
+    def _create_access_token(self, identity, fresh=False, expires_delta=None):
         if expires_delta is None:
             expires_delta = config.access_expires
 

flask_jwt_extended/utils.py

@@ -76,14 +76,49 @@ def _get_jwt_manager():
                            "application before using this method")
 
 
-def create_access_token(*args, **kwargs):
+def create_access_token(identity, fresh=False, expires_delta=None):
+    """
+    Creates a new access token
+
+    :param identity: The identity of this token. This can be any data that is
+                     json serializable. It can also be an object, in which case
+                     you can use the user_identity_loader to define a function
+                     that will be called to pull a json serializable identity
+                     out of this object. This is useful so you don't need to
+                     query disk twice, once for initially finding the identity
+                     in your login endpoint, and once for setting addition data
+                     in the JWT via the user_claims_loader
+    :param fresh: If this token should be marked as fresh, and can thus access
+                  fresh_jwt_required protected endpoints. Defaults to False
+    :param expires_delta: A datetime.timedelta for how long this token should
+                          last before it expires. If this is None, it will
+                          use the 'JWT_ACCESS_TOKEN_EXPIRES` config value
+    :return: A new access token
+    """
+
     jwt_manager = _get_jwt_manager()
-    return jwt_manager.create_access_token(*args, **kwargs)
+    return jwt_manager._create_access_token(identity, fresh, expires_delta)
 
 
-def create_refresh_token(*args, **kwargs):
+def create_refresh_token(identity, expires_delta=None):
+    """
+    Creates a new refresh token
+
+    :param identity: The identity of this token. This can be any data that is
+                     json serializable. It can also be an object, in which case
+                     you can use the user_identity_loader to define a function
+                     that will be called to pull a json serializable identity
+                     out of this object. This is useful so you don't need to
+                     query disk twice, once for initially finding the identity
+                     in your login endpoint, and once for setting addition data
+                     in the JWT via the user_claims_loader
+    :param expires_delta: A datetime.timedelta for how long this token should
+                          last before it expires. If this is None, it will
+                          use the 'JWT_REFRESH_TOKEN_EXPIRES` config value
+    :return: A new refresh token
+    """
     jwt_manager = _get_jwt_manager()
-    return jwt_manager.create_refresh_token(*args, **kwargs)
+    return jwt_manager._create_refresh_token(identity, expires_delta)
 
 
 def has_user_loader():