docs: auto-document privilege levels

bin/cylc-make-docs

@@ -38,7 +38,7 @@ echo "Building the HTML Cylc Documentation with Sphinx:"
 echo >&2
 cd "$CYLC_DIR"/doc/
 echo "... Generating the command reference ..."
-./src/custom/make-commands.sh
+#./src/custom/make-commands.sh
 echo >&2
 
 echo "... Generating multi-page User Guide..."

doc/src/api/zmq.rst

@@ -27,6 +27,16 @@ The available "commands" or ("endpoints") are contained in
 :py:class:`cylc.network.server.SuiteRuntimeServer` class.
 
 
+Privilege Levels
+----------------
+
+Cylc protects its network interface with configurable privilege levels which
+can be used to allocate different levels of control to different users.
+
+.. autoclass:: cylc.network.Priv
+   :members:
+
+
 Client
 ------
 

doc/src/appendices/site-user-config-ref.rst

@@ -1095,23 +1095,7 @@ password.
 This sets the client privilege level for public access - i.e. no
 suite passphrase required.
 
-- *type*: string (must be one of the following options)
-- *options*:
+- *type*: string (must be one of the following options).
+- *options*: A Cylc privilege level: :py:obj:`cylc.network.Priv`.
 
-  none
-     Permit no public suite access.
-  identity
-     Only suite and owner names revealed.
-  description
-     Identity plus suite title and description.
-  state-totals
-     Identity, description, and task state totals.
-  read
-     Full read-only access.
-  shutdown
-     *Not yet implemented*
-     Full read access plus shutdown, but no other control.
-  control
-     Permit full control (not recommended).
-
-- *default*: state-totals
+- *default*: :py:obj:`cylc.network.Priv.STATE_TOTALS`

doc/src/running-suites.rst

@@ -504,23 +504,9 @@ server program is determined by the public access privilege level set in global
 site/user config (:ref:`GlobalAuth`) and optionally overidden in suites
 (:ref:`SuiteAuth`):
 
-none
-   Permit no public suite access.
-identity
-   Only suite and owner names revealed.
-description
-   Identity plus suite title and description.
-state-totals
-   Identity, description, and task state totals.
-read
-   Full read-only access.
-shutdown
-   *Not yet implemented*
-   Full read access plus shutdown, but no other control.
-control
-   Permit full control (not recommended).
-
-The default public access level is *state-totals*.
+See Cylc privilege levels: :py:obj:`cylc.network.Priv`.
+
+The default public access level is :py:obj:`cylc.network.Priv.STATE_TOTALS`.
 
 The ``cylc scan`` command can print
 descriptions and task state totals in addition to basic suite identity, if the

lib/cylc/network/__init__.py

@@ -30,18 +30,36 @@
 
 
 class Priv(IntEnum):
-    """Cylc privilege level."""
+    """Cylc privilege levels.
 
-    # TODO - autodocument from this class.
-    # TODO - revert name changes?
+    In Cylc configurations use the lower-case form of each privilege level
+    e.g. ``control`` for ``Priv.CONTORL``.
+
+    These levels are ordered (by the integer associated with each) from 0.
+    Each privilege level grants access to the levels below it.
+
+    """
 
     CONTROL = 6
+    """Provides full control of a suite."""
+
     SHUTDOWN = 5  # (Not used yet - for the post-passphrase era.)
+    """Allows issuing of the shutdown command."""
+
     READ = 4
+    """Permits read access to the suite's state."""
+
     STATE_TOTALS = 3
+    """Provides access to the count of tasks in each state."""
+
     DESCRIPTION = 2
+    """Permits reading of suite metadata."""
+
     IDENTITY = 1
+    """Provides read access to the suite name, owner and Cylc version."""
+
     NONE = 0
+    """No access."""
 
     @classmethod
     def parse(cls, key):

lib/cylc/network/server.py

@@ -240,6 +240,9 @@ def _authorise(self, *args, user='?', meta=None, **kwargs):
             LOG.info(
                 '[client-command] %s %s@%s:%s', fcn.__name__, user, host, prog)
             return fcn(self, *args, **kwargs)
+        _authorise.__doc__ += (  # add auth level to docstring
+            'Authentication:\n%s:py:obj:`cylc.network.%s`\n' % (
+                ' ' * 12, req_priv_level))
         return _authorise
     return wrapper