Clarify generic authenticator setup documentation

docs/topic/authenticator-configuration.rst

@@ -18,28 +18,32 @@ can be used with TLJH. A number of them ship by default with TLJH:
    their password when they log in for the first time. Default authenticator used in TLJH.
 
 We try to have specific how-to guides & tutorials for common authenticators. Since we can not cover
-everything, this guide shows you how to use any authenticator you want by using LDAPAuthenticator as an
+everything, this guide shows you how to use any authenticator you want with JupyterHub by following
-example.
+the authenticator's documentation.
 
-Configuring the authenticator
+Setting authenticator properties
-=============================
+================================
 
-Some authenticators have unique configuration options. This section covers a
+JupyterHub authenticators are customized by setting *traitlet properties*. In the authenticator's
-few common ones.
+documentation, you will find these are usually represented as:
 
-LDAPAuthenticator
+.. code-block::
-^^^^^^^^^^^^^^^^^
 
-LDAPAuthenticator's `documentation <https://github.com/jupyterhub/ldapauthenticator#required-configuration>`_
+   c.<AuthenticatorName>.<property-name> = <some-value>
-lists the various configuration options you can set for LDAPAuthenticator. You can set them
+
-in TLJH with the following pattern:
+You can set these with ``tljh-config`` with:
 
 .. code-block:: bash
 
-   sudo -E tljh-config set auth.<authenticator-name>.<config-option-name> <config-option-value>
+   sudo -E tljh-config set auth.<AuthenticatorName>.<property-name> <some-value>
 
-When the documentation asks you to set ``LDAPAuthenticator.server_address`` to some
+Example
-value, you can do that with the following command:
+-------
+
+LDAPAuthenticator's `documentation <https://github.com/jupyterhub/ldapauthenticator#required-configuration>`_
+lists the various configuration options you can set for LDAPAuthenticator.
+When the documentation asks you to set ``LDAPAuthenticator.server_address``
+to some value, you can do that with the following command:
 
 .. code-block:: bash
 
@@ -52,23 +56,19 @@ Enabling the authenticator
 ==========================
 
 Once you have configured the authenticator as you want, you should then
-enable it. We'll use the LDAPAuthenticator as an example, though the process
+enable it. Usually, the documentation for the authenticator would ask you to add
-is similar for the other authenticators.
+something like the following to your ``jupyterhub_config.py`` to enable it:
+
+.. code-block:: python
+
+   c.JupyterHub.authenticator_class = 'fully-qualified-authenticator-name'
+
+You can accomplish the same with ``tljh-config``:
 
 .. code-block:: bash
 
    sudo -E tljh-config set auth.type <fully-qualified-authenticator-name>
 
-For LDAPAuthenticator, the fully qualified name is ``ldapauthenticator.LDAPAuthenticator``.
-This is the same name that the documentation `asks <https://github.com/jupyterhub/ldapauthenticator#usage>`_
-you to set ``c.JupyterHub.authenticator_class`` to.
-
-For LDAPAuthenticator, this would be:
-
-.. code-block:: bash
-
-   sudo -E tljh-config set auth.type ldapauthenticator.LDAPAuthenticator
-
 Once enabled, you need to reload JupyterHub for the config to take effect.
 
 .. code-block:: bash
@@ -78,3 +78,15 @@ Once enabled, you need to reload JupyterHub for the config to take effect.
 Try logging in a separate incognito window to check if your configuration works. This
 lets you preserve your terminal in case there were errors. If there are
 errors, :ref:`troubleshooting/logs` should help you debug them.
+
+Example
+-------
+
+From the `documentation <https://github.com/jupyterhub/ldapauthenticator#usage>`_ for
+LDAPAuthenticator, we see that the fully qualified name is ``ldapauthenticator.LDAPAuthenticator``.
+Assuming you have already configured it, the following commands enable LDAPAuthenticator.
+
+.. code-block:: bash
+
+   sudo -E tljh-config set auth.type ldapauthenticator.LDAPAuthenticator
+   sudo -E tljh-config reload