More Sphinx autodocs.

sqliter · Aug 30, 2017 · c36cf3f · c36cf3f
1 parent d7bc6b2
commit c36cf3f
Show file tree

Hide file tree

Showing 10 changed files with 107 additions and 75 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -183,16 +183,9 @@
 
 # -- Autodoc ---
 add_module_names = False    # Remove module paths from docs
-
-# Always show __init__() methods
-def skip_member_except_init(app, what, name, obj, skip, options):
-    if name == '__init__':
-        return False
-    return skip
-
-# Always show __init__() methods
-def setup(app):
-    app.connect("autodoc-skip-member", skip_member_except_init)
+autodoc_default_flags = ['members', 'undoc-members', 'inherited-members']
+autodoc_member_order = 'bysource'
+autoclass_content = 'both'   # Show class doc, but not __init__ doc
 
 # -- Global substitutions
 rst_epilog = """

diff --git a/docs/source/flask_user_api.rst b/docs/source/flask_user_api.rst
@@ -19,14 +19,12 @@ Flask-User API
 UserManager class
 -----------------
 
-This is the main class that implements most of Flask-User's functionality.
+This class implements most of Flask-User's functionality.
 
-Flask-User can be customized by extending methods such as the ``customize()`` method
+Flask-User can be customized by implementing the ``customize()`` method.
 
 .. autoclass:: flask_user.user_manager.UserManager
-    :members:
-    :inherited-members:
-    :undoc-members:
+    :no-undoc-members:
 
 --------
 
@@ -35,19 +33,9 @@ Flask-User can be customized by extending methods such as the ``customize()`` me
 EmailManager class
 ------------------
 
-The EmailManager manages the emails the Flask-User sends:
-
-- ‘email confirmation’ email.
-- ‘password has changed’ notification email.
-- ‘reset password’ email.
-- ‘user has registered’ notification email.
-- ‘user invitation’ email.
-- ‘username has changed’ notification email.
+This class manages the sending of Flask-User emails.
 
 .. autoclass:: flask_user.email_manager.EmailManager
-    :members:
-    :inherited-members:
-    :undoc-members:
 
 --------
 
@@ -65,9 +53,7 @@ These tokens are used in the following places:
 * To provide secure tokens in reset-password emails.
 
 .. autoclass:: flask_user.token_manager.TokenManager
-    :members:
-    :inherited-members:
-    :undoc-members:
+    :no-undoc-members:
 
 --------
 
@@ -88,9 +74,6 @@ Included implementations:
 Other databases can be supported by adding additional interface implementation classes.
 
 .. autoclass:: flask_user.db_adapters.db_adapter.DbAdapter
-    :members:
-    :inherited-members:
-    :undoc-members:
 
 --------
 
@@ -110,7 +93,4 @@ Included implementations:
 Other email mailers can be supported by adding additional interface implementation classes.
 
 .. autoclass:: flask_user.email_mailers.email_mailer.EmailMailer
-    :members:
-    :inherited-members:
-    :undoc-members:
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,3 +1,9 @@
+.. topic:: Attention
+
+    Flask-User v1.0 is under active development.
+
+    Please use `Flask-User v0.6 <http://flask-user.readthedocs.io/en/v0.6/>`_ for now.
+
 .. include:: ../../README.rst
 
 Table of Contents

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -4,8 +4,22 @@ Installation
 
 We recommend making use of virtualenv, virtualenvwrapper and pip::
 
+    # Create virtual enviroment
     mkvirtualenv my_app
+
+    # Switch to virtual environment
     workon my_app
-    pip install flask-user
 
+    # Install Flask-User
+    pip install Flask-User
+
+Because Flask-User defaults to sending emails with Flask-Mail and managing databases with Flask-SQLAlchemy,
+Flask-User will install these packages by default.
+
+If you configure Flask-User to use a different mailer or a different
+object-database mapper, you may uninstall unused packages::
+
+    # Optionally uninstall unused packages
+    pip uninstall Flask-Mail
+    pip uninstall Flask-SQLAlchemy
 
diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
@@ -1 +1,8 @@
+.. topic:: Attention
+
+    Flask-User v1.0 is under active development.
+
+    Please use `Flask-User v0.6 <http://flask-user.readthedocs.io/en/v0.6/>`_ for now.
+
+
 .. include:: ../../README.rst
diff --git a/docs/source/misc_api.rst b/docs/source/misc_api.rst
@@ -14,9 +14,7 @@ DbAdapterForSQLAlchemy
 ----------------------
 
 .. autoclass:: flask_user.db_adapters.db_adapter_for_sqlalchemy.DbAdapterForSQLAlchemy
-    :members:
-    :inherited-members:
-    :undoc-members:
+    :member-order: alphabetical
 
 --------
 
@@ -26,38 +24,33 @@ DbAdapterForMongoAlchemy
 ------------------------
 
 .. autoclass:: flask_user.db_adapters.db_adapter_for_mongoalchemy.DbAdapterForMongoAlchemy
-    :members:
-    :inherited-members:
-    :undoc-members:
+    :member-order: alphabetical
 
 
+--------
+
 .. _EmailMailerForFlaskMail:
 
 EmailMailerForFlaskMail
 -----------------------
 
 .. autoclass:: flask_user.email_mailers.email_mailer_for_flask_mail.EmailMailerForFlaskMail
-    :members:
-    :inherited-members:
-    :undoc-members:
+
+--------
 
 .. _EmailMailerForFlaskSendmail:
 
 EmailMailerForFlaskSendmail
 ---------------------------
 
 .. autoclass:: flask_user.email_mailers.email_mailer_for_flask_sendmail.EmailMailerForFlaskSendmail
-    :members:
-    :inherited-members:
-    :undoc-members:
+
+--------
 
 .. _EmailMailerForSendgrid:
 
 EmailMailerForSendgrid
 ----------------------
 
 .. autoclass:: flask_user.email_mailers.email_mailer_for_sendgrid.EmailMailerForSendgrid
-    :members:
-    :inherited-members:
-    :undoc-members:
 
diff --git a/flask_user/email_manager.py b/flask_user/email_manager.py
@@ -17,6 +17,10 @@ class EmailManager(object):
     """ Send emails via the configured Email Mailer ``user_manager.email_mailer``. """
 
     def __init__(self, user_manager):
+        """
+        Args:
+            user_manager: The Flask-User instance.
+        """
         self.user_manager = user_manager
 
     def send_email_confirmation_email(self, user, user_email):

diff --git a/flask_user/token_manager.py b/flask_user/token_manager.py
@@ -25,10 +25,9 @@ class TokenManager(object):
     # *** Public methods ***
 
     def __init__(self, flask_secret_key):
-        """Initialize the TokenManager class
-
+        """
         Args:
-            flask_secret_key (str): The secret key used to encrypt and decrypt tokens.
+            flask_secret_key(str): The secret key used to encrypt and decrypt tokens.
                 This is typically Flask's SECRET_KEY setting.
                 Preferably 32 bytes or longer, but spaces will be padded if needed.
         """
@@ -115,7 +114,7 @@ def encrypt_string(self, concatenated_str):
         return token_str
 
     def decrypt_string(self, token_str, expiration_in_seconds):
-        """Verify signature, verify timestamp, and decrypts a token using ``cryptography.fernet.Fernet()``."""
+        """Verify signature, verify timestamp, and decrypt a token using ``cryptography.fernet.Fernet()``."""
 
         # Add '=' padding if needed
         if len(token_str) % 4:

diff --git a/flask_user/user_manager.py b/flask_user/user_manager.py
@@ -31,10 +31,17 @@ def _flask_user_context_processor():
         user_manager=current_app.user_manager,
         call_or_get=_call_or_get)
 
+
+# Define custom Exception
+class ConfigurationError(Exception):
+    pass
+
+
 # The UserManager is implemented across several source code files.
 # Mixins are used to aggregate all member functions into the one UserManager class.
 class UserManager():
-    """ Customizable User Authentication and Management."""
+    """ Customizable User Authentication and Management.
+    """
 
     # ***** Initialization methods *****
 
@@ -43,11 +50,16 @@ def __init__(self, app=None, db=None, UserClass=None, **kwargs):
         Args:
             app(Flask): The Flask application instance.
             db: An Object-Database Mapper instance such as SQLAlchemy or MongoAlchemy.
-            UserClass: The User data-model Class (*not* an instance!)
+            UserClass: The User class (*not* an instance!).
+
         Keyword Args:
-            UserEmailClass: The optional UserEmail data-model Class (*not* an instance!).
-                Needed for the multiple emails per user feature.
+            UserEmailClass: The optional UserEmail class (*not* an instance!).
+                Required for the 'multiple emails per user' feature.
+            UserInvitationClass: The optional UserInvitation class (*not* an instance!).
+                Required for the 'register by invitation' feature.
 
+        Example:
+            ``user_manager = UserManager(app, db, User)``
         """
 
         #see http://flask.pocoo.org/docs/0.12/extensiondev/#the-extension-code """
@@ -101,15 +113,25 @@ def init_app(self, app, db, UserClass,
                             % app.__class__.__name__)
 
         # Configure a DbAdapter based on the class of the 'db' parameter
-        from flask_sqlalchemy import SQLAlchemy
-        if isinstance(db, SQLAlchemy):
-            from .db_adapters import DbAdapterForSQLAlchemy
-            self.db_adapter = DbAdapterForSQLAlchemy(db)
-
-        from flask_mongoalchemy import MongoAlchemy
-        if isinstance(db, MongoAlchemy):
-            from .db_adapters import DbAdapterForMongoAlchemy
-            self.db_adapter = DbAdapterForMongoAlchemy(db)
+        self.db_adapter = None
+        # Check if db is a SQLAlchemy instance
+        if self.db_adapter is None:
+            try:
+                from flask_sqlalchemy import SQLAlchemy
+                if isinstance(db, SQLAlchemy):
+                    from .db_adapters import DbAdapterForSQLAlchemy
+                    self.db_adapter = DbAdapterForSQLAlchemy(db)
+            except:
+                pass
+        # Check if db is a MongoAlchemy instance
+        if self.db_adapter is None:
+            try:
+                from flask_mongoalchemy import MongoAlchemy
+                if isinstance(db, MongoAlchemy):
+                    from .db_adapters import DbAdapterForMongoAlchemy
+                    self.db_adapter = DbAdapterForMongoAlchemy(db)
+            except:
+                pass
 
         # Configure EmailMailerForFlaskMail as the defaule email mailer
         from .email_mailers.email_mailer_for_flask_mail import EmailMailerForFlaskMail
@@ -359,9 +381,8 @@ def _create_default_attr(self, attribute_name, default_value):
     def _check_settings(self):
         """ Verify config combinations. Produce a helpful error messages for inconsistent combinations."""
 
-        # Define custom Exception
-        class ConfigurationError(Exception):
-            pass
+        if self.db_adapter is None:
+            raise ConfigurationError('You must specify a DbAdapter interface or install Flask-SQLAlchemy or FlaskMongAlchemy.')
 
         # USER_ENABLE_REGISTER=True must have USER_ENABLE_USERNAME=True or USER_ENABLE_EMAIL=True or both.
         if self.enable_register and not (self.enable_username or self.enable_email):
@@ -409,15 +430,19 @@ def _add_url_routes(self, app):
             app.add_url_rule(self.invite_url, 'user.invite', self.invite_view_function, methods=['GET', 'POST'])
 
     def get_user_by_id(self, user_id):
+        """Retrieve a User by ID."""
         return self.db_adapter.get_object(self.UserClass, user_id)
 
     def get_user_email_by_id(self, user_email_id):
+        """Retrieve a UserEmail by ID."""
         return self.db_adapter.get_object(self.UserEmailClass, user_email_id)
 
     def find_user_by_username(self, username):
+        """Retrieve a User by username."""
         return self.db_adapter.ifind_first_object(self.UserClass, username=username)
 
     def find_user_by_email(self, email):
+        """Retrieve a User by email."""
         if self.UserEmailClass:
             user_email = self.db_adapter.ifind_first_object(self.UserEmailClass, email=email)
             user = user_email.user if user_email else None
@@ -428,14 +453,22 @@ def find_user_by_email(self, email):
         return (user, user_email)
 
     def email_is_available(self, new_email):
-        """ Return True if new_email does not exist.
-            Return False otherwise."""
+        """Check if ``new_email`` is available.
+
+        | Returns True if ``new_email`` does not exist or belongs to the current user.
+        | Return False otherwise.
+        """
+
         user, user_email = self.find_user_by_email(new_email)
         return (user==None)
 
     def username_is_available(self, new_username):
-        """ Return True if new_username does not exist or if new_username equals old_username.
-            Return False otherwise."""
+        """Check if ``new_username`` is available.
+
+        | Returns True if ``new_username`` does not exist or belongs to the current user.
+        | Return False otherwise.
+        """
+
         # Allow user to change username to the current username
         if _call_or_get(current_user.is_authenticated):
             current_username = current_user.username
@@ -445,6 +478,7 @@ def username_is_available(self, new_username):
         return self.find_user_by_username(new_username)==None
 
     def get_primary_user_email(self, user):
+        """Retrieve the primary User email for the 'multiple emails per user' feature."""
         db_adapter = self.db_adapter
         if self.UserEmailClass:
             user_email = db_adapter.find_first_object(self.UserEmailClass,

diff --git a/setup.py b/setup.py
@@ -43,6 +43,8 @@ def load_readme():
     install_requires=[
         'Flask>=0.9',
         'Flask-Login>=0.3',
+        'Flask-Mail>=0.9',
+        'Flask-SQLAlchemy>=1.0',
         'Flask-WTF>=0.9',
         'bcrypt>=1.1',
         'cryptography>=2.0',