Minimally document Cylc Review (to later extend)

bin/cylc-check-software

@@ -57,6 +57,7 @@ opt_spec = {
     'urllib3': [None, 'HTTPSCOMMS', 'PY'],
     'pygtk': [(2, 0), 'GUIORGRAPH', 'PY'],
     'pygraphviz': [None, 'GUIORGRAPH', 'PY'],
+    'cherrypy': [None, 'REVIEW', 'PY'],
     'texlive': [None, 'LATEXGUIDE', 'TEX'],
     'tocloft': [None, 'LATEXGUIDE', 'TEX'],
     'framed': [None, 'LATEXGUIDE', 'TEX'],
@@ -81,6 +82,7 @@ func_tags_and_text = {
     'TEMPLATING': 'configuration templating',
     'HTTPSCOMMS': 'HTTPS communications layer',
     'GUIORGRAPH': 'GUI & dependency graph visualisation',
+    'REVIEW': 'Cylc Review web service',
     'LATEXGUIDE': 'LaTeX User Guide',
     'HTMLUGUIDE': 'HTML User Guide'
 }

doc/src/cylc-user-guide/cug.tex

@@ -1203,6 +1203,80 @@ \subsection{Locating Suite And Task Output}
     such as \lstinline=$CYLC_SUITE_SHARE_DIR=, see~\ref{TaskExecutionEnvironment}.
 \end{myitemize}
 
+\subsection{Viewing Suite Logs via Web Browser: Cylc Review}
+
+Cylc provides a utility for viewing the status and logs of suites called
+Cylc Review. Cylc Review displays suite information in web pages, as shown in
+Figure~\ref{fig-review-screenshot}.
+
+\begin{figure}
+    \begin{center}
+        \includegraphics[width=0.5\textwidth]{graphics/png/orig/cylc-review-screenshot.png}
+    \end{center}
+    \caption{Screenshot of a Cylc Review web page}
+\label{fig-review-screenshot}
+\end{figure}
+
+If a Cylc Review server is provided at your site, you can open the Cylc
+Review page for a suite by running the \lstinline=cylc review= command.
+See~\ref{HostsforCylcReview} for requirements and~\ref{ConfiguringCylcReview}
+for configuration steps for setting up a host to run the Cylc Review service
+at your site.
+
+Otherwise an ad-hoc web server can be set up using the
+\lstinline=cylc review start= command argument.
+
+\subsubsection{Hosts For Running Cylc Review}
+\label{HostsforCylcReview}
+
+Installation requirements:
+
+\begin{myitemize}
+
+\item Bash
+\item Python
+\item cherrypy
+\item Jinja2.
+
+\end {myitemize}
+
+Connectivity requirements:
+
+\begin{myitemize}
+
+\item Must be able to access the home directories of users' Cylc run
+directories.
+
+\end {myitemize}
+
+\subsubsection{Configuring Cylc Review}
+\label{ConfiguringCylcReview}
+
+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:
+
+\hilight{\lstinline=setsid /path/to/../cylc review start 0</dev/null 1>/dev/null 2>\&1 \&=}
+
+You will find the access and error logs under \lstinline=~/.cylc/cylc-review*=.
+
+Alternatively you can run the Cylc Review web service under Apache
+\lstinline=mod_wsgi=. To do this you will need to set up an Apache module
+configuration file (typically in
+\lstinline=/etc/httpd/conf.d/rose-wsgi.conf=) containing the following (with
+the paths set appropriately):
+
+\lstset{language=bash}
+\begin{lstlisting}
+WSGIPythonPath /path/to/rose/lib/python
+WSGIScriptAlias /cylc-review /path/to/lib/cylc/review.py
+\end{lstlisting}
+
+Use the Apache log at e.g. \lstinline=/var/log/httpd/= to debug problems.
+
 \subsection{Remote Tasks}
 \label{RemoteTasks}