Update with changes to docs (converted to RST) from cylc#2924 merge

doc/src/external-triggers.rst

@@ -25,7 +25,7 @@ broker.
 
 External triggers are visible in suite visualizations as bare graph nodes (just
 the trigger names). They are plotted against all dependent tasks, not in a
-cycle point specific way like tasks. This is because external triggers may or 
+cycle point specific way like tasks. This is because external triggers may or
 may not be cycle point (or even task name) specific - it depends on the
 arguments passed to the corresponding trigger functions. For example, if an
 external trigger does not depend on task name or cycle point it will only be
@@ -66,7 +66,7 @@ the main process. The clock trigger function signature looks like this:
 The ``offset`` argument is a date-time duration (``PT1H`` is 1
 hour) relative to the dependent task's cycle point (automatically passed to the
 function via a second argument not shown above).
- 
+
 In the following suite, task ``foo`` has a daily cycle point sequence,
 and each task instance can trigger once the wall clock time has passed its
 cycle point value by one hour:
@@ -154,7 +154,7 @@ Try starting the downstream suite first, then the upstream, and
 watch what happens.
 In each cycle point the ``@upstream`` trigger in the downstream suite
 waits on the task ``foo`` (with the same cycle point) in the upstream
-suite to emit the *data ready* message. 
+suite to emit the *data ready* message.
 
 Some important points to note about this:
 
@@ -163,7 +163,7 @@ Some important points to note about this:
   ``PT10S`` (i.e. 10 seconds, which is also the default value).
 - the ``suite_state`` trigger function, like the
   ``cylc suite-state`` command, must have read-access to the upstream
-  suite's public database. 
+  suite's public database.
 - the cycle point argument is supplied by a string template
   ``%(point)s``. The string templates available to trigger function
   arguments are described in :ref:`Custom Trigger Functions`).
@@ -194,7 +194,7 @@ To see this, take a look at the job script for one of the downstream tasks:
 
 .. code-block:: bash
 
-   % cylc cat-log -f j dn f2.2011 
+   % cylc cat-log -f j dn f2.2011
    ...
    cylc__job__inst__user_env() {
        # TASK RUNTIME ENVIRONMENT:
@@ -347,7 +347,7 @@ function signature is:
 
    xrandom(percent, secs=0, _=None, debug=False)
 
-The ``percent`` argument sets the odds of success in any given call; 
+The ``percent`` argument sets the odds of success in any given call;
 ``secs`` is the number of seconds to sleep before returning; and the
 ``_`` argument (underscore is a conventional name for a variable
 that is not used, in Python) is provided to allow specialization of the trigger

doc/src/installation.rst

@@ -39,8 +39,7 @@ the Cylc GUIs:
   - python-devel
   - graphviz-devel
 
-The Cylc Review service does not need any further packages to those
-already required (Python 2) and bundled with Cylc (CherryPy and Jinja2).
+The Cylc Review service does not need any additional packages.
 
 The following packages are necessary for running all the tests in Cylc:
 
@@ -65,30 +64,30 @@ are installed properly:
    ===============================================================================
    Package (version requirements)                          Outcome (version found)
    ===============================================================================
-                                 *REQUIRED SOFTWARE*                              
+                                 *REQUIRED SOFTWARE*
    Python (2.6+, <3).....................FOUND & min. version MET (2.7.12.final.0)
 
-          *OPTIONAL SOFTWARE for the GUI & dependency graph visualisation*       
+          *OPTIONAL SOFTWARE for the GUI & dependency graph visualisation*
    Python:pygraphviz (any)...........................................NOT FOUND (-)
    graphviz (any)...................................................FOUND (2.26.0)
    Python:pygtk (2.0+)...............................................NOT FOUND (-)
 
-               *OPTIONAL SOFTWARE for the HTTPS communications layer*            
+               *OPTIONAL SOFTWARE for the HTTPS communications layer*
    Python:requests (2.4.2+)......................FOUND & min. version MET (2.11.1)
    Python:urllib3 (any)..............................................NOT FOUND (-)
    Python:OpenSSL (any)..............................................NOT FOUND (-)
 
-                *OPTIONAL SOFTWARE for the configuration templating*             
+                *OPTIONAL SOFTWARE for the configuration templating*
    Python:EmPy (any).................................................NOT FOUND (-)
 
-                   *OPTIONAL SOFTWARE for the HTML documentation*                
+                   *OPTIONAL SOFTWARE for the HTML documentation*
    Python:sphinx (1.5.3+).........................FOUND & min. version MET (1.7.0)
    ===============================================================================
 
    Summary:
-                            ****************************                         
-                                Core requirements: ok                             
-                             Full-functionality: not ok                          
+                            ****************************
+                                Core requirements: ok
+                             Full-functionality: not ok
                             ****************************
 
 If errors are reported then the packages concerned are either not installed or
@@ -217,6 +216,54 @@ appropriate contents.
 The job will attempt to source the first of these files it finds to set up its
 environment.
 
+
+.. _ConfiguringCylcReviewApache:
+
+Configuring Cylc Review Under Apache
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Cylc Review web service displays suite job logs and other information in
+web pages - see :ref:`ViewingSuiteLogsCylcReview` and
+:numref:`fig-review-screenshot`. It can run under a WSGI server (e.g.
+Apache with ``mod_wsgi``) as a service for all users, or as an ad hoc
+service under your own user account.
+
+To run Cylc Review under Apache, install ``mod_wsgi`` and configure it
+as follows, with paths modified appropriately:
+
+.. code-block:: bash
+
+   # Apache mod_wsgi config file, e.g.:
+   #   Red Hat Linux: /etc/httpd/conf.d/cylc-wsgi.conf
+   #   Ubuntu Linux: /etc/apache2/mods-available/wsgi.conf
+   # E.g. for /opt/cylc-7.8.1/
+   WSGIPythonPath /opt/cylc-7.8.1/lib
+   WSGIScriptAlias /cylc-review /opt/cylc-7.8.1/bin/cylc-review
+
+(Note the ``WSGIScriptAlias`` determines the service URL under the
+server root).
+
+And allow Apache access to the Cylc library:
+
+.. code-block:: bash
+
+   # Directory access, in main Apache config file, e.g.:
+   #   Red Hat Linux: /etc/httpd/conf/httpd.conf
+   #   Ubuntu Linux: /etc/apache2/apache2.conf
+   # E.g. for /opt/cylc-7.8.1/
+   <Directory /opt/cylc-7.8.1/>
+	   AllowOverride None
+	   Require all granted
+   </Directory>
+
+The host running the Cylc Review web service, and the service itself (or the
+user that it runs as) must be able to view the ``~/cylc-run`` directory
+of all Cylc users.
+
+Use the web server log, e.g. ``/var/log/httpd/`` or ``/var/log/apache2/``, to
+debug problems.
+
+
 .. _RTAST:
 
 Automated Tests

doc/src/running-suites.rst

@@ -82,7 +82,7 @@ before being shut down or killed.
 
    $ cylc restart SUITE
 
-Tasks recorded in the "submitted" or "running" states are automatically polled 
+Tasks recorded in the "submitted" or "running" states are automatically polled
 (see :ref:`Task Job Polling`) at start-up to determine what happened to
 them while the suite was down.
 
@@ -557,7 +557,7 @@ The gcylc GUI is mainly a network client to retrieve and display suite status
 information from the suite server program, but it can also invoke file-reading
 commands to view and graph the suite configuration and so on. This is entirely
 transparent if the GUI is running on the suite host account, but full
-functionality for remote suites requires either a shared filesystem, or 
+functionality for remote suites requires either a shared filesystem, or
 (see :ref:`RemoteControl`) auth file installation *and* non-interactive ssh
 access to the suite host.  Without the auth files you will not be able
 to connect to the suite, and without ssh you will see "permission denied"
@@ -608,7 +608,7 @@ is the suite name. Client commands should then be invoked with the
    Remote suite auth files do not need to be installed for read-only
    access - see :ref:`PublicAccess` - via the GUI or monitor.
 
-The suite contact file (see :ref:`The Suite Contact File`) is not needed if 
+The suite contact file (see :ref:`The Suite Contact File`) is not needed if
 you have read-access to the remote suite run directory via the local
 filesystem or non-interactive ssh to the suite host account - client commands
 will automatically read it. If you do install the contact file in your auth

doc/src/tutorial.rst

@@ -513,12 +513,19 @@ with the ``cylc cat-log`` command:
   ``$CYLC_SUITE_SHARE_DIR``, see :ref:`TaskExecutionEnvironment`.
 
 
-Viewing Suite Logs via Web Browser: Cylc Review
------------------------------------------------
+.. _ViewingSuiteLogsCylcReview:
 
-Cylc provides a utility for viewing the status and logs of suites called
-Cylc Review. It displays suite information in web pages, as shown in
-:numref:`fig-review-screenshot`.
+Viewing Suite Logs in a Web Browser: Cylc Review
+------------------------------------------------
+
+The Cylc Review web service displays suite job logs and other information in
+web pages, as shown in :numref:`fig-review-screenshot`. It can run under a
+WSGI server (e.g. Apache with ``mod_wsgi``) as a service for all
+users, or as an ad hoc service under your own user account.
+
+If a central Cylc Review service has been set up at your site (e.g. as
+described in :ref:`ConfiguringCylcReviewApache`) the URL will typically be
+something like ``http://<server>/cylc-review/``.
 
 .. _fig-review-screenshot:
 
@@ -527,55 +534,17 @@ Cylc Review. It displays suite information in web pages, as shown in
 
    Screenshot of a Cylc Review web page
 
-If a Cylc Review server is provided at your site, you can open the Cylc
-Review page for a suite by running the ``cylc review`` command.
-See :ref:`HostsforCylcReview` for requirements and
-:ref:`ConfiguringCylcReview` for configuration steps for setting up a
-host to run the service at your site.
-
-Otherwise an ad-hoc web server can be set up using the
-``cylc review start`` command argument.
-
-
-.. _HostsforCylcReview:
-
-Hosts For Running Cylc Review
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Connectivity requirements:
-
-- Must be able to access the home directories of users' Cylc run directories.
-
-
-.. _ConfiguringCylcReview:
+Otherwise, to start an ad hoc Cylc Review service to view your own suite logs
+(or those of others, if you have read access to them), run:
 
-Configuring Cylc Review
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Cylc Review can provide an intranet web service at your site for users to
-view their suite logs using a web browser. Depending on settings at your
-site, you may or may not be able to set up this service
-(see :ref:`HostsforCylcReview`).
-
-You can start an ad-hoc Cylc Review web server by running:
-
-.. code-block:: bash
-
-   setsid /path/to/../cylc review start 0</dev/null 1>/dev/null 2>\&1 \&
-
-You will find the access and error logs under ``~/.cylc/cylc-review*``.
-
-Alternatively you can run the Cylc Review web service under Apache
-``mod_wsgi``. To do this you will need to set up an Apache module
-configuration file (typically in ``/etc/httpd/conf.d/cylc-wsgi.conf``)
-containing the following (with the paths set appropriately):
-
-.. code-block:: bash
+.. code-block:: none
 
-   WSGIPythonPath /path/to/cylc/lib
-   WSGIScriptAlias /cylc-review /path/to/lib/cylc/review.py
+   setsid cylc review start 0</dev/null 1>/dev/null 2>&1 &
 
-Use the Apache log at e.g. ``/var/log/httpd/`` to debug problems.
+The service should start at ``http://<server>:8080`` (the port number
+can optionally be set on the command line). Service logs are written to
+``~/.cylc/cylc-review*``. Run ``cylc review`` to view
+status information, and ``cylc review stop`` to stop the service.
 
 
 .. _RemoteTasks: