Improve docs (#977)

Made a sweep through all the docs and fixed/improved things:

- added missing recoverY_codes API
- added missing change_email signals
- many openapi requests had a missing 'type: string' so didn't render
- added sphinx extension autosectionlabel to make it easier to link
- moved overview and search to top of doc pages (for some long pages like API - it was hard to find them at the bottom).

CHANGES.rst

@@ -968,7 +968,7 @@ Released March 31, 2020
 
 Features
 ++++++++
-- (:pr:`257`) Support a unified sign in feature. Please see :ref:`unified-sign-in`.
+- (:pr:`257`) Support a unified sign in feature. Please see :ref:`configuration:unified signin`.
 - (:pr:`265`) Add phone number validation class. This is used in both unified sign in
   as well as two-factor when using ``sms``.
 - (:pr:`274`) Add support for 'freshness' of caller's authentication. This permits endpoints

docs/api.rst

@@ -337,6 +337,20 @@ sends the following signals.
    Sent when a user requests a password reset. In addition to the app (which is
    the sender), it is passed `user`, `token` (deprecated), and `reset_token` arguments.
 
+.. data:: change_email_instructions_sent
+
+    Sent when a user requests to change their registered email address. In addition to the
+    app (which is the sender) it is passed `user`, `token`, and `new_email`.
+
+    .. versionadded:: 5.5.0
+
+.. data:: change_email_confirmed
+
+    Sent when a user has confirmed their new email address. In addition to the
+    app (which is the sender) it is passed `user`, `old_email`.
+
+    .. versionadded:: 5.5.0
+
 .. data:: tf_code_confirmed
 
     Sent when a user performs two-factor authentication login on the site. In

docs/conf.py

@@ -33,6 +33,7 @@
     "pallets_sphinx_themes",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.autosectionlabel",
     "sphinx_issues",
 ]
 
@@ -114,6 +115,8 @@
 autodoc_type_aliases = {
     "CbType": "oauth_provider.CbType",
 }
+autosectionlabel_prefix_document = True
+autosectionlabel_maxdepth = 2
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
@@ -175,7 +178,7 @@
 # Custom sidebar templates, maps document names to template names.
 html_sidebars = {
     "index": ["project.html", "localtoc.html", "searchbox.html"],
-    "**": ["localtoc.html", "relations.html", "searchbox.html"],
+    "**": ["relations.html", "searchbox.html", "localtoc.html"],
 }
 singlehtml_sidebars = {"index": ["project.html", "localtoc.html"]}
 

docs/configuration.rst

@@ -85,7 +85,7 @@ These configuration keys are used globally across all features.
 
 .. py:data:: SECURITY_PASSWORD_SCHEMES
 
-    List of support password hash algorithms. ``SECURITY_PASSWORD_HASH``
+    List of supported password hash algorithms. ``SECURITY_PASSWORD_HASH``
     must be from this list. Passwords encrypted with any of these schemes will be honored.
 
 .. py:data:: SECURITY_DEPRECATED_PASSWORD_SCHEMES
@@ -108,7 +108,7 @@ These configuration keys are used globally across all features.
 .. py:data:: SECURITY_PASSWORD_SINGLE_HASH
 
     A list of schemes that should not be hashed twice. By default, passwords are
-    hashed twice, first with ``SECURITY_PASSWORD_SALT``, and then with a random salt.
+    hashed twice, first with :py:data:`SECURITY_PASSWORD_SALT`, and then with a random salt.
 
     Default: a list of known schemes not working with double hashing (`django_{digest}`, `plaintext`).
 
@@ -347,7 +347,7 @@ These configuration keys are used globally across all features.
 
     .. versionchanged:: 4.1.0
         The 'key' attribute was deprecated in favor of a separate configuration
-        variable ``SECURITY_CSRF_COOKIE_NAME``.
+        variable :data:`SECURITY_CSRF_COOKIE_NAME`.
 
 .. py:data:: SECURITY_CSRF_HEADER
 
@@ -805,7 +805,7 @@ Registerable
 
     Specifies the view to redirect to after a user successfully registers.
     This value can be set to a URL or an endpoint name. If this value is
-    ``None``, the user is redirected to the value of ``SECURITY_POST_LOGIN_VIEW``.
+    ``None``, the user is redirected to the value of :data:`SECURITY_POST_LOGIN_VIEW`.
     Note that if the request URL or form has a ``next`` parameter, that will take precedence.
 
     Default: ``None``.
@@ -912,7 +912,7 @@ Confirmable
 
     Specifies the view to redirect to after a user successfully confirms their email.
     This value can be set to a URL or an endpoint name. If this value is ``None``, the user is redirected to the
-    value of ``SECURITY_POST_LOGIN_VIEW``.
+    value of :data:`SECURITY_POST_LOGIN_VIEW`.
 
     Default: ``None``.
 .. py:data:: SECURITY_AUTO_LOGIN_AFTER_CONFIRM
@@ -927,7 +927,7 @@ Confirmable
 .. py:data:: SECURITY_LOGIN_WITHOUT_CONFIRMATION
 
     Specifies if a user may login before confirming their email when
-    the value of ``SECURITY_CONFIRMABLE`` is set to ``True``.
+    the value of :data:`SECURITY_CONFIRMABLE` is set to ``True``.
 
     Default: ``False``.
 .. py:data:: SECURITY_REQUIRES_CONFIRMATION_ERROR_VIEW
@@ -957,7 +957,7 @@ Configuration variables for the ``SECURITY_CHANGEABLE`` feature:
     Specifies the view to redirect to after a user successfully changes their password.
     This value can be set to a URL or an endpoint name.
     If this value is ``None``, the user is redirected  to the
-    value of ``SECURITY_POST_LOGIN_VIEW``.
+    value of :data:`SECURITY_POST_LOGIN_VIEW`.
 
     Default: ``None``.
 .. py:data:: SECURITY_CHANGE_PASSWORD_TEMPLATE
@@ -1078,7 +1078,7 @@ Recoverable
 
     Default: ``_("Your password has been reset")``.
 
-Change_Email
+Change-Email
 ------------
 .. versionadded:: 5.5.0
 
@@ -1154,7 +1154,7 @@ Configuration related to the two-factor authentication feature.
     Specifies if Flask-Security should enable the two-factor login feature.
     If set to ``True``, in addition to their passwords, users will be required to
     enter a code that is sent to them. Note that unless
-    ``SECURITY_TWO_FACTOR_REQUIRED`` is set - this is opt-in.
+    :data:`SECURITY_TWO_FACTOR_REQUIRED` is set - this is opt-in.
 
     Default: ``False``.
 .. py:data:: SECURITY_TWO_FACTOR_REQUIRED
@@ -1404,8 +1404,8 @@ Unified Signin
 .. py:data:: SECURITY_US_ENABLED_METHODS
 
     Specifies the default enabled methods for unified signin authentication.
-    Be aware that ``password`` only affects this ``SECURITY_US_SIGNIN_URL`` endpoint.
-    Removing it from here won't stop users from using the ``SECURITY_LOGIN_URL`` endpoint
+    Be aware that ``password`` only affects this :data:`SECURITY_US_SIGNIN_URL` endpoint.
+    Removing it from here won't stop users from using the :data:`SECURITY_LOGIN_URL` endpoint
     (unless you replace the login endpoint using :py:data:`SECURITY_US_SIGNIN_REPLACES_LOGIN`).
 
     This config variable defines which methods can be used to provide authentication data.
@@ -1654,7 +1654,7 @@ WebAuthn
         - ``"secondary"`` - just keys registered as "secondary" are allowed
 
     If list is empty or ``None`` WebAuthn keys aren't allowed. This also means that the
-            :py:data:``SECURITY_WAN_VERIFY`` endpoint won't be registered.
+            :py:data:`SECURITY_WAN_VERIFY_URL` endpoint won't be registered.
 
     Default: ``["first", "secondary"]``
 

docs/features.rst

@@ -99,12 +99,10 @@ expiry value (settable via the :data:`SECURITY_TOKEN_EXPIRE_TIMESTAMP` callable)
     there are some endpoints that require session information (e.g. a session cookie).
     Please read :ref:`freshness_topic` and :ref:`csrf_topic`
 
-.. _two-factor:
-
 Two-factor Authentication
 ----------------------------------------
-
-Two-factor authentication is enabled by generating time-based one time passwords
+If :ref:`configured<configuration:Two-Factor>`,
+the two-factor authentication feature generates time-based one time passwords
 (Tokens). The tokens are generated using the users `totp secret`_, which is unique
 per user, and is generated both on first login, and when changing the two-factor
 method (doing this causes the previous totp secret to become invalid). The token
@@ -121,13 +119,12 @@ they lose track of their secondary factor device. Rescue options include sending
 a one time code via email, send an email to the application admin, and using a previously
 generated and downloaded one-time code (see :py:data:`SECURITY_MULTI_FACTOR_RECOVERY_CODES`).
 
-.. _unified-sign-in:
-
 Unified Sign In
 ---------------
 **This feature is in Beta - mostly due to it being brand new and little to no production soak time**
 
-Unified sign in provides a generalized login endpoint that takes an `identity`
+If :ref:`configured<configuration:Unified Signin>`,
+a generalized login endpoint is provided that takes an `identity`
 and a `passcode`; where (based on configuration):
 
     * `identity` is any of :py:data:`SECURITY_USER_IDENTITY_ATTRIBUTES` (e.g. email, username, phone)
@@ -172,20 +169,18 @@ If you disable the freshness check then sessions aren't required.
     * Registration and Confirmation only work with email - so while you can enable multiple
       authentication methods, you still have to register with email.
 
-.. _webauthn:
-
 WebAuthn
----------------
+--------
 **This feature is in Beta - mostly due to it being brand new and little to no production soak time**
 
 WebAuthn is a standardized protocol that connects authenticators (such as YubiKey and mobile biometrics)
-with websites. Flask-Security supports using WebAuthn keys as either 'first' or 'secondary'
+with websites. If :ref:`configured<configuration:WebAuthn>`, Flask-Security supports using WebAuthn keys as either 'first' or 'secondary'
 authenticators. Please read :ref:`webauthn_topic` for more details.
 
 Email Confirmation
 ------------------
-
-If desired you can require that new users confirm their email address.
+If :ref:`configured<configuration:Confirmable>`, your application
+can require that new users confirm their email address prior to allowing them to authenticate.
 Flask-Security will send an email message to any new users with a confirmation
 link. Upon navigating to the confirmation link, the user's account will be set to
 'confirmed'. The user can then sign in usually the normal mechanisms.
@@ -194,11 +189,10 @@ if the user happens to try to use an expired token or has lost the previous
 email. Confirmation links can be configured to expire after a specified amount
 of time (default 5 days).
 
-
 Password Reset/Recovery
 -----------------------
-
-Password reset and recovery is available for when a user forgets their
+If :ref:`configured<configuration:Recoverable>`,
+password reset and recovery is available for when a user forgets their
 password. Flask-Security sends an email to the user with a link to a view which
 allows them to reset their password. Once the password is reset they are redirected to
 the login page where they need to authenticate using the new password.
@@ -210,8 +204,7 @@ which will invalidate all existing sessions AND (by default) all authentication
 
 User Registration
 -----------------
-
-Flask-Security comes packaged with a basic user registration view. This view is
+If :ref:`configured<configuration:Registerable>`, Flask-Security provides a basic user registration view. This view is
 very simple and new users need only supply an email address and their password.
 This view can be overridden if your registration process requires more fields.
 User email is validated and normalized using the
@@ -224,7 +217,7 @@ able to authenticate with EITHER email or username - however that can be changed
 
 Password Change
 ---------------
-Flask-Security comes packaged with a basic change user password view. Unlike password
+If :ref:`configured<configuration:Changeable>` users can change their password. Unlike password
 recovery, this endpoint is used when the user is already authenticated. The result
 of a successful password change is not only a new password, but a new value for ``fs_uniquifier``.
 This has the effect is immediately invalidating all existing sessions. The change request
@@ -238,13 +231,13 @@ when generating authentication tokens and so won't be affected by password chang
 
 Email Change
 ------------
-If configured, users can change the email they registered with. This will send a new confirmation email to the new email address.
+If :ref:`configured<configuration:Change-Email>`, users can change the email they registered with. This will send a new confirmation email to the new email address.
 
 
 Login Tracking
 --------------
 
-Flask-Security can, if configured, keep track of basic login events and
+Flask-Security can, if :ref:`configured<configuration:Trackable>`, keep track of basic login events and
 statistics. They include:
 
 * Last login date