cylc hub: document multi-user config post jupyter server v2 upgrade

* Auto-spawning of other user's servers can now be configured.
* Jupyter Server security policy must be defined if Jupyter Lab
  or any other server extension is included in the deployment.
* Simplify some sections and expand on the new configurations.

Author: oliver-sanders

src/7-to-8/major-changes/ui.rst

@@ -45,7 +45,11 @@ and as a multi user hub, ``cylc hub``. Both are dependent on `Cylc UI Server`_ i
 Launching the UI via the hub will require authentication.
 The default Authenticator uses PAM to authenticate system users with their
 username and password.
-Going via the hub unlocks the :ref:`Authorization` feature.
+
+Going via the hub unlocks the ability to grant other users the permission
+to view and interact with workflows running under your account.
+Site administrators will need to configure this, for more information
+see :ref:`cylc.uiserver.multi-user`.
 
 .. figure:: ../../img/hub.png
    :figwidth: 80%

src/conf.py

@@ -110,6 +110,8 @@
 autosummary_imported_members = False
 
 # Mapping to other Sphinx projects we want to import references from.
+# NOTE: To work search available references, use:
+# $ python -m sphinx.ext.intersphinx <url>/objects.inv | less
 intersphinx_mapping = {
     'rose': (
         'http://metomi.github.io/rose/2.1.0/html', None
@@ -119,6 +121,9 @@
     ),
     'jupyter_server': (
         'https://jupyter-server.readthedocs.io/en/latest/', None
+    ),
+    'jupyter_hub': (
+        'https://jupyterhub.readthedocs.io/en/stable/', None
     )
 }
 

src/reference/architecture/ui-server.rst

@@ -92,8 +92,14 @@ spawns UI Servers on behalf of users and provides each with a fixed URL
 Users can access each other's UI Servers providing they have been granted
 permission.
 
-Authorization is performed by Cylc within the `Cylc UI Server`_, see
-:ref:`cylc authorization`.
+*Authentication* is provided by either `Jupyter Server`_ or `Jupyter Hub`_.
+
+*Authorization* in the `Cylc UI Server`_ is provided by Cylc. In
+multi-user mode this allows users to connect to each others UI Servers for
+monitoring or control purposes.
+
+For more information on security and configuration see
+:ref:`cylc.uiserver.multi-user`.
 
 .. _Jupyter Hub technical overview: https://jupyterhub.readthedocs.io/en/stable/reference/technical-overview.html
 
@@ -109,24 +115,3 @@ For information on the architecture of `Jupyter Hub`_ and the
 
 .. image:: img/gui-arch-multi-user.svg
    :width: 100%
-
-
-.. _cylc authorization:
-
-Authorization
--------------
-
-*Authentication* is provided by either `Jupyter Server`_ or `Jupyter Hub`_.
-
-*Authorization* in the `Cylc UI Server`_ is provided by Cylc. In
-multi-user mode this allows users to connect to each others UI Servers for
-monitoring or control purposes.
-
-See also :ref:`Authorization`.
-
-.. note::
-
-   This authorization only applies to the ``/cylc`` endpoints managed by the
-   Cylc extension.  Other `Jupyter Server`_ extensions such as `Jupyter Lab`_
-   do not share this authorization and will not be accessible to other users
-   (unless they can be configured to allow this).

src/reference/changes.rst

@@ -20,6 +20,36 @@ For more detail see the component changelogs:
 * `metomi-rose-changelog`_
 * `metomi-isodatetime-changelog`_
 
+
+----------
+
+Cylc 8.3.0
+----------
+
+.. admonition:: Cylc Components
+   :class: hint
+
+   TODO
+
+..
+   Uncomment this before 8.3.0 release
+
+   :cylc-flow: `8.2 <https://github.com/cylc/cylc-flow/blob/8.3.x/CHANGES.md>`__
+   :cylc-uiserver: `1.3 <https://github.com/cylc/cylc-uiserver/blob/1.4.x/CHANGES.md>`__
+   :cylc-rose: `1.3 <https://github.com/cylc/cylc-rose/blob/1.4.x/CHANGES.md>`__
+
+
+Upgrade To The Latest Jupyter Releases
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Cylc UI Server has been updated to work with the latest releases of
+`Jupyter Server`_ and `Jupyter Hub`_.
+
+If you are utilising Cylc's multi-user functionality then your configuration
+will require some changes to work with these releases.
+
+See :ref:`cylc.uiserver.multi-user` for more details
+
 ----------
 
 Cylc 8.2.0