Document Flask-User settings through autodoc.

CHANGES.rst

@@ -1,5 +1,5 @@
-Change Log
-==========
+Change history
+==============
 
 * v1.0 -- Initial version.
 

README.rst

@@ -30,7 +30,7 @@ Secure and Reliable
 Fully customizable, yet Ready to use
 ------------------------------------
 * **Largely configurable** -- Through configuration settings
-* **Fully customizable** -- Through customizable functions and email templates
+* **Almost fully customizable** -- Through customizable functions and email templates
 * **Ready to use** -- Through sensible defaults
 * Supports **SQL Databases** and **MongoDB Databases**
 * **Event hooking** -- Through signals

docs/source/_static/custom.css

@@ -0,0 +1,6 @@
+/* Switch off word hyphenation */
+div.body p,
+div.body dd,
+div.body li {
+    hyphens: None;
+}

docs/source/api.rst

@@ -73,7 +73,7 @@ Typical use:
                 # Customize the DB Adapter for SQLAlchemy with this User model
                 self.db_adapter = SQLAlchemyAdapter(db, User)
                 # Customize Flask-User settings
-                self.enable_email = True
+                self.USER_ENABLE_EMAIL = True
 
         # Setup Flask-User
         user_manager = CustomUserManager(app)
@@ -90,7 +90,7 @@ As an a alternative, user_manager.init_app(app) can be used::
             # Customize the DB Adapter for SQLAlchemy with this User model
             self.db_adapter = SQLAlchemyAdapter(db, User)
             # Customize Flask-User settings
-            self.enable_email = True
+            self.USER_ENABLE_EMAIL = True
 
     db = SQLAlchemy(app)                            # Setup SQLAlchemy
     user_manager = CustomUserManager(UserManager)   # Setup Flask-User

docs/source/authorization.rst

@@ -41,7 +41,7 @@ In the example below the current user is required to have the 'admin' role::
 Note: Comparison of role names is case sensitive, so 'Member' will NOT match 'member'.
 
 Multiple string arguments -- the AND operation
-~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The @roles_required decorator accepts multiple strings if the current_user is required to have
 **ALL** of these roles.
@@ -54,7 +54,7 @@ In the example below the current user is required to have the **ALL** of these r
 Multiple string arguments represent the 'AND' operation.
 
 Array arguments -- the OR operation
-~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The @roles_required decorator accepts an array (or a tuple) of roles.
 
@@ -65,7 +65,7 @@ In the example below the current user is required to have **One or more** of the
     # Array arguments require at least ONE of these roles.
 
 AND/OR operations
-~~~~~~~~
+~~~~~~~~~~~~~~~~~
 The potentially confusing syntax described above allows us to construct
 complex AND/OR operations.
 
@@ -83,7 +83,7 @@ Note: The nesting level only goes as deep as this example shows.
 
 
 Required Tables
---------------
+---------------
 
 For @login_required only the User model is required
 

docs/source/conf.py

@@ -187,6 +187,10 @@
 autodoc_member_order = 'bysource'
 autoclass_content = 'both'   # Show class doc, but not __init__ doc
 
+def setup(app):
+    # Disable word hyphenation by HTML/CSS
+    app.add_stylesheet('custom.css')
+
 # -- Global substitutions
 rst_epilog = """
 .. |supported_python_versions_and| replace:: {supported_python_versions_and}

docs/source/configure.rst

@@ -0,0 +1,32 @@
+Configure
+=========
+
+Flask-User is designed to be **largely configurable** and **almost fully customizable**.
+
+Flask-User default features and settings can overridden in one of two ways:
+
+1) By changing the settings in the application config file::
+
+    # Customize Flask-User settings
+    USER_ENABLE_EMAIL = True
+    USER_ENABLE_USERNAME = False
+
+2) By changing the setting in the ``UserManager.customize()``::
+
+    # Customize Flask-User
+    class CustomUserManager(UserManager):
+
+        def customize(self):
+            # Customize Flask-User settings
+            self.USER_ENABLE_EMAIL = True
+            self.USER_ENABLE_USERNAME = False
+
+The :ref:`UserManager` documents all Flask-User settings (over 70 of them).
+
+If a setting is defined in both the application config file and in ``UserManager.customize()``,
+the ``UserManager.customize()`` setting will override the config file setting.
+
+To keep the code base simple and robust, we offer no easy way to change
+the '/user' base URL or the '/flask_user' base directory in bulk.
+Please copy them from the :ref:`UserManager` docs use your editor to find-and-replace these bases.
+

docs/source/customization.rst → docs/source/customize.rst

@@ -155,7 +155,7 @@ and define the confirmation specific messages in ``templates/flask_user/emails/c
 The email template files, along with available template variables listed below:
 
 * Template variables available in any email template
-    * ``user_manager`` - For example: ``{% if user_manager.enable_confirm_email %}``
+    * ``user_manager`` - For example: ``{% if user_manager.USER_ENABLE_CONFIRM_EMAIL %}``
     * ``user`` - For example: ``{{ user.email }}``
 * templates/flask_user/confirm_email_[subject.txt|message.html|message.txt]
     * ``confirm_email_link`` - For example: ``{{ confirm_email_link }}``

docs/source/index.rst

@@ -18,15 +18,16 @@ Table of Contents
     limitations
     data_models
     porting
-    changes
+    configure
+    customize
     flask_user_api
     authorization
     roles_required_app
     base_templates
-    customization
     signals
     recipes
     internationalization
     faq
+    changes
 
 

docs/source/misc_api.rst

@@ -4,7 +4,8 @@ Miscellaneous API
 - DbAdapterForSQLAlchemy_
 - DbAdapterForMongoAlchemy_
 - EmailMailerForFlaskMail_
-- SendmailEmailMailer_
+- EmailMailerForFlaskSendmail_
+- EmailMailerForSendgrid_
 
 --------
 

docs/source/porting.rst

@@ -42,15 +42,17 @@ appropriate DbAdapter will be configured internally.
 
 Configuration settings changes
 ------------------------------
-we renamed the `PASSWORD_HASH` setting to `PASSWORD_HASH_SCHEME` to better reflect what this setting means.
+We split ``USER_SHOW_USERNAME_EMAIL_DOES_NOT_EXIST`` into ``USER_SHOW_USERNAME_DOES_NOT_EXIST``
+and ``USER_SHOW_EMAIL_DOES_NOT_EXIST`` and set the default to False for increased security.
 
 Flask-User v0.6::
 
-    USER_PASSWORD_HASH = 'brcypt'
+    USER_SHOW_USERNAME_EMAIL_DOES_NOT_EXIST = True
 
 Flask-User v1.0::
 
-    USER_PASSWORD_HASH_SCHEME = 'brcypt'
+    USER_SHOW_EMAIL_DOES_NOT_EXIST = False
+    USER_SHOW_USERNAME_DOES_NOT_EXIST = False
 
 
 Data-model changes
@@ -105,7 +107,7 @@ We changed the `verify_user_password()` parameter order to be consistent with th
 
 We renamed `update_password()` to `update_user_hashed_password()` to better reflect what this method does.
 
-we renamed the `PASSWORD_HASH` setting to `PASSWORD_HASH_SCHEME` to better reflect what this setting means.
+we renamed the `PASSWORD_HASH` setting to `PASSWORD_HASH` to better reflect what this setting means.
 
 Flask-User v0.6::
 

flask_user/email_manager.py

@@ -27,8 +27,8 @@ def send_email_confirmation_email(self, user, user_email):
         """Send the 'email confirmation' email."""
 
         # Verify email settings
-        if not self.user_manager.enable_email: return
-        if not self.user_manager.send_registered_email and not self.user_manager.enable_confirm_email: return
+        if not self.user_manager.USER_ENABLE_EMAIL: return
+        if not self.user_manager.USER_SEND_REGISTERED_EMAIL and not self.user_manager.USER_ENABLE_CONFIRM_EMAIL: return
 
         # Generate confirm email link
         object_id = user_email.id if user_email else user.id
@@ -41,9 +41,9 @@ def send_email_confirmation_email(self, user, user_email):
 
         # Render subject, html message and text message
         subject, html_message, text_message = self._render_email(
-                self.user_manager.confirm_email_email_template,
+                self.user_manager.USER_CONFIRM_EMAIL_EMAIL_TEMPLATE,
                 user=user,
-                app_name=self.user_manager.app_name,
+                app_name=self.user_manager.USER_APP_NAME,
                 confirm_email_link=confirm_email_link)
 
         # Send email message using Flask-Mail
@@ -53,8 +53,8 @@ def send_password_has_changed_email(self, user):
         """Send the 'password has changed' notification email."""
 
         # Verify email settings
-        if not self.user_manager.enable_email: return
-        if not self.user_manager.send_password_changed_email: return
+        if not self.user_manager.USER_ENABLE_EMAIL: return
+        if not self.user_manager.USER_SEND_PASSWORD_CHANGED_EMAIL: return
 
         # Retrieve email address from User or UserEmail object
         user_email = self.get_primary_user_email(user)
@@ -64,9 +64,9 @@ def send_password_has_changed_email(self, user):
 
         # Render subject, html message and text message
         subject, html_message, text_message = self._render_email(
-                self.user_manager.password_changed_email_template,
+                self.user_manager.USER_PASSWORD_CHANGED_EMAIL_TEMPLATE,
                 user=user,
-                app_name=self.user_manager.app_name)
+                app_name=self.user_manager.USER_APP_NAME)
 
         # Send email message using Flask-Mail
         self._send_email_message(email, subject, html_message, text_message)
@@ -75,8 +75,8 @@ def send_reset_password_email(self, user, user_email):
         """Send the 'reset password' email."""
 
         # Verify email settings
-        if not self.user_manager.enable_email: return
-        assert self.user_manager.enable_forgot_password
+        if not self.user_manager.USER_ENABLE_EMAIL: return
+        assert self.user_manager.USER_ENABLE_FORGOT_PASSWORD
 
         # Generate reset password link
         token = self.user_manager.token_manager.generate_token(user.id)
@@ -88,9 +88,9 @@ def send_reset_password_email(self, user, user_email):
 
         # Render subject, html message and text message
         subject, html_message, text_message = self._render_email(
-            self.user_manager.forgot_password_email_template,
+            self.user_manager.USER_FORGOT_PASSWORD_EMAIL_TEMPLATE,
             user=user,
-            app_name=self.user_manager.app_name,
+            app_name=self.user_manager.USER_APP_NAME,
             reset_password_link=reset_password_link)
 
         # Send email message using Flask-Mail
@@ -107,9 +107,9 @@ def send_user_invitation_email(self, user):
 
         # Render subject, html message and text message
         subject, html_message, text_message = self._render_email(
-                self.user_manager.invite_email_template,
+                self.user_manager.USER_INVITE_EMAIL_TEMPLATE,
                 user=user,
-                app_name=self.user_manager.app_name,
+                app_name=self.user_manager.USER_APP_NAME,
                 accept_invite_link=accept_invite_link)
 
         # Send email message using Flask-Mail
@@ -119,18 +119,18 @@ def send_user_has_registered_email(self, user, user_email, confirm_email_link):
         """Send the 'user has registered' notification email."""
 
         # Verify email settings
-        if not self.user_manager.enable_email: return
-        if not self.user_manager.send_registered_email: return
+        if not self.user_manager.USER_ENABLE_EMAIL: return
+        if not self.user_manager.USER_SEND_REGISTERED_EMAIL: return
 
         # Retrieve email address from User or UserEmail object
         email = user_email.email if user_email else user.email
         assert(email)
 
         # Render subject, html message and text message
         subject, html_message, text_message = self._render_email(
-                self.user_manager.registered_email_template,
+                self.user_manager.USER_REGISTERED_EMAIL_TEMPLATE,
                 user=user,
-                app_name=self.user_manager.app_name,
+                app_name=self.user_manager.USER_APP_NAME,
                 confirm_email_link=confirm_email_link)
 
         # Send email message using Flask-Mail
@@ -140,8 +140,8 @@ def send_username_has_changed_email(self, user):  # pragma: no cover
         """Send the 'username has changed' notification email."""
 
         # Verify email settings
-        if not self.user_manager.enable_email: return
-        if not self.user_manager.send_username_changed_email: return
+        if not self.user_manager.USER_ENABLE_EMAIL: return
+        if not self.user_manager.USER_SEND_USERNAME_CHANGED_EMAIL: return
 
         # Retrieve email address from User or UserEmail object
         user_email = self.get_primary_user_email(user)
@@ -151,9 +151,9 @@ def send_username_has_changed_email(self, user):  # pragma: no cover
 
         # Render subject, html message and text message
         subject, html_message, text_message = self._render_email(
-                self.user_manager.username_changed_email_template,
+                self.user_manager.USER_USERNAME_CHANGED_EMAIL_TEMPLATE,
                 user=user,
-                app_name=self.user_manager.app_name)
+                app_name=self.user_manager.USER_APP_NAME)
 
         # Send email message using Flask-Mail
         self._send_email_message(email, subject, html_message, text_message)