Assorted updates

Rebase branch to updated master to include all recent changes Amend Cylc homepage 'index' page Amend .gitignore to include all generated docs content Amend documentation/00-make.t to account for new make method Amend relevant tests to account for changed [documentation][files]
cylc · Dec 23, 2018 · 4732a6d · 4732a6d
1 parent 5ccf7e5
commit 4732a6d
Show file tree

Hide file tree

Showing 12 changed files with 40 additions and 92 deletions.
diff --git a/.gitignore b/.gitignore
@@ -2,19 +2,12 @@
 # python bytecode
 *.pyc
 
-# Generated documentation files.
-# - User Guide.
-doc/src/cylc-user-guide/pdf
-doc/src/cylc-user-guide/html
-doc/src/cylc-user-guide/commands.tex
-doc/src/cylc-user-guide/cylc-version.txt
-# - Suite Design Guide.
-doc/src/suite-design-guide/*.aux
-doc/src/suite-design-guide/*.out
-doc/src/suite-design-guide/*.pdf
-doc/src/suite-design-guide/*.log
-doc/src/suite-design-guide/*.toc
-# Installed docs.
+# Generated documentation files (from 'cylc make-docs')
+# - Command reference from called script 'custom/make-commands.sh'.
+doc/src/appendices/command-ref.rst
+# - Main directory of generated sphinx docs (guides) files.
+doc/built-sphinx/
+# - Installed docs
 doc/install/
 
 # VERSION FILE

diff --git a/bin/cylc-make-docs b/bin/cylc-make-docs
@@ -35,13 +35,18 @@ if [[ $# != 0 ]]; then
 fi
 
 echo >&2
-echo "Building the HTML Cylc Documentation with Sphinx..."
+echo "Building the HTML Cylc Documentation with Sphinx:"
 echo >&2
 cd "$CYLC_DIR"/doc/
-echo "Generating the command reference..."
+echo "... Generating the command reference ..."
 ./src/custom/make-commands.sh
 echo >&2
-echo "Auto-generating the HTML with Sphinx..."
-sphinx-build -n -b html ./src install/
+
+echo "... Generating the Cylc homepage index..."
+./src/custom/make-index.sh
+echo >&2
+
+echo "... Auto-generating the HTML with Sphinx ..."
+sphinx-build -n -b html ./src built-sphinx/
 echo >&2
 echo "Done."
diff --git a/doc/src/appendices/suiterc-config-ref.rst b/doc/src/appendices/suiterc-config-ref.rst
@@ -357,6 +357,7 @@ substituted with actual values:
 - \%(event)s: event name (see below)
 - \%(suite)s: suite name
 - \%(suite\_url)s: suite URL
+- \%(suite\_uuid)s: suite UUID string
 - \%(message)s: event message, if any
 - any suite [meta] item, e.g.:
   - \%(title)s: suite title
@@ -1764,6 +1765,7 @@ will be substituted with actual values:
 
 - \%(event)s: event name
 - \%(suite)s: suite name
+- \%(suite\_uuid)s: suite UUID string
 - \%(point)s: cycle point
 - \%(name)s: task name
 - \%(submit\_num)s: submit number

diff --git a/doc/src/homepage/index.css → doc/src/custom/index.css b/doc/src/homepage/index.css → doc/src/custom/index.css
@@ -23,7 +23,7 @@ div.uberpage {
 div.page {
     color:#00b3fd;
     background:white;
-    background-image:url(graphics/cylc-logo.png);
+    background-image:url(graphics/png/orig/cylc-logo.png);
     background-repeat:no-repeat;
     background-position: top right;
     margin:0 auto;

diff --git a/doc/src/homepage/make-index.sh → doc/src/custom/make-index.sh b/doc/src/homepage/make-index.sh → doc/src/custom/make-index.sh
@@ -20,20 +20,16 @@
 
 set -e
 
+# All paths relative to the '$CYLC_HOME/doc/' directory.
 OUT=install
 rm -rf $OUT
 mkdir -p $OUT
-cp src/index.css $OUT
-cp -r src/cylc-user-guide/graphics $OUT
-cp src/cylc-logo.png $OUT/graphics
-
-CYLC_VERSION=$($(dirname $0)/../../bin/cylc --version)
+cp src/custom/index.css $OUT
+cp -r src/graphics $OUT
+CYLC_VERSION=$($(dirname $0)/../../../bin/cylc --version)
 INDEX=$OUT/index.html
 
-CUG_PDF=src/cylc-user-guide/pdf/cug-pdf.pdf
-CUG_HTML_SINGLE=src/cylc-user-guide/html/single/
-CUG_HTML_MULTI=src/cylc-user-guide/html/multi/
-SDG_PDF=src/suite-design-guide/document.pdf
+HTML_DOCS=built-sphinx/
 
 cat > $INDEX <<__END__
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
@@ -64,61 +60,19 @@ cylc COMMAND --help
 </div>
 
 <div class="lbox">
-<h3 style="margin:10px">User Guide</h3>
-<ul>
-__END__
-
-if [[ -f $CUG_PDF ]]; then
-  cp $CUG_PDF $OUT/cylc-user-guide.pdf
-  cat >> $INDEX <<__END__
-  <li><a href="cylc-user-guide.pdf">PDF</a></li>
-__END__
-else
-    cat >> $INDEX <<__END__
-    <li>PDF <i>(not generated)</i></li>
-__END__
-fi
-
-mkdir -p $OUT/html
-if [[ -f $CUG_HTML_SINGLE/cug-html.html ]]; then
-  cp -r $CUG_HTML_SINGLE $OUT/html/single
-  cat >> $INDEX <<__END__
-  <li><a href="html/single/cug-html.html">HTML (single page)</a> </li>
-__END__
-else
-    cat >> $INDEX <<__END__
-    <li>HTML single page <i>(not generated)</i></li>
-__END__
-fi
-
-if [[ -f $CUG_HTML_MULTI/cug-html.html ]]; then
-  cp -r $CUG_HTML_MULTI $OUT/html/multi
-  cat >> $INDEX <<__END__
-  <li><a href="html/multi/cug-html.html">HTML (multi page)</a></li>
-__END__
-else
-    cat >> $INDEX <<__END__
-    <li>HTML multi page <i>(not generated)</i></li>
-__END__
-fi
-
-cat >> $INDEX <<__END__
-</ul>
-</div>
-
-<div class="lbox">
-<h3 style="margin:10px">Suite Design Guide</h3>
+<h3 style="margin:10px">HTML Guides: User Guide & Suite Design Guide</h3>
 <ul>
 __END__
 
-if [[ -f $SDG_PDF ]]; then
-  cp $SDG_PDF $OUT/suite-design-guide.pdf
+mkdir -p $OUT/html/
+if [[ -f $HTML_DOCS/index.html ]]; then
+  cp -r $HTML_DOCS $OUT/html/
   cat >> $INDEX <<__END__
-  <li><a href="suite-design-guide.pdf">PDF</a></li>
+  <li><a href="html/built-sphinx.html">HTML (multi page)</a></li>
 __END__
 else
     cat >> $INDEX <<__END__
-    <li>PDF <i>(not generated)</i></li>
+    <li>HTML Guides multi page <i>(not generated)</i></li>
 __END__
 fi
 

diff --git a/doc/src/homepage/cylc-logo.png b/doc/src/homepage/cylc-logo.png
diff --git a/doc/src/tutorial.rst b/doc/src/tutorial.rst
@@ -567,12 +567,12 @@ 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/rose-wsgi.conf``)
+configuration file (typically in ``/etc/httpd/conf.d/cylc-wsgi.conf``)
 containing the following (with the paths set appropriately):
 
 .. code-block:: bash
 
-   WSGIPythonPath /path/to/rose/lib/python
+   WSGIPythonPath /path/to/cylc/lib
    WSGIScriptAlias /cylc-review /path/to/lib/cylc/review.py
 
 Use the Apache log at e.g. ``/var/log/httpd/`` to debug problems.

diff --git a/lib/cylc/cfgspec/globalcfg.py b/lib/cylc/cfgspec/globalcfg.py
@@ -90,7 +90,7 @@
     'documentation': {
         'files': {
             'html user guides': [
-                VDR.V_STRING, '$CYLC_DIR/doc/install/index.html'],
+                VDR.V_STRING, '$CYLC_DIR/doc/built-sphinx/index.html'],
         },
         'urls': {
             'internet homepage': [VDR.V_STRING, 'http://cylc.github.io/cylc/'],

diff --git a/tests/cylc-doc/00-cylc-doc.t b/tests/cylc-doc/00-cylc-doc.t
@@ -23,19 +23,16 @@ set_test_number 2
 create_test_globalrc "" "
 [documentation]
    [[files]]
-      pdf user guide = ${PWD}/doc/pdf/cug-pdf.pdf
-      multi-page html user guide = /home/bob/cylc/cylc.git/doc/html/multi/cug-html.html
-      html index = /home/bob/cylc/cylc.git/doc/index.html
-      single-page html user guide = /home/bob/cylc/cylc.git/doc/html/single/cug-html.html
+      html user guides = ${PWD}/doc/built-sphinx/index.html
    [[urls]]
       internet homepage = http://cylc.github.com/cylc/
       local index = http://localhost/cylc/index.html"
 #-------------------------------------------------------------------------------
-mkdir -p doc/pdf
-touch doc/pdf/cug-pdf.pdf
-cylc doc -s -p > stdout1.txt
+mkdir -p doc/built-sphinx
+touch doc/built-sphinx/index.html
+cylc doc -s -g > stdout1.txt
 cmp_ok stdout1.txt <<__END__
-$PWD/doc/pdf/cug-pdf.pdf
+${PWD}/doc/built-sphinx/index.html
 __END__
 #-------------------------------------------------------------------------------
 cylc doc -s > stdout2.txt

diff --git a/tests/cylc-doc/01-suite-urls.t b/tests/cylc-doc/01-suite-urls.t
@@ -26,10 +26,7 @@ set_test_number 3
 create_test_globalrc "" "
 [documentation]
    [[files]]
-      pdf user guide = ${PWD}/doc/pdf/cug-pdf.pdf
-      multi-page html user guide = /home/bob/cylc/cylc.git/doc/html/multi/cug-html.html
-      html index = /home/bob/cylc/cylc.git/doc/index.html
-      single-page html user guide = /home/bob/cylc/cylc.git/doc/html/single/cug-html.html
+      html user guides = ${PWD}/doc/built-sphinx/index.html
    [[urls]]
       internet homepage = http://cylc.github.com/cylc/
       local index = http://localhost/cylc/index.html"

diff --git a/tests/cylc-get-site-config/00-basic.t b/tests/cylc-get-site-config/00-basic.t
@@ -32,7 +32,7 @@ run_ok $TEST_NAME.doc-section-python \
 run_ok $TEST_NAME.multiple-secs \
     cylc get-site-config --item='[documentation]' --item='[hosts]'
 run_ok $TEST_NAME.doc-entry \
-    cylc get-site-config --item='[documentation][files]html index'
+    cylc get-site-config --item='[documentation][files]html user guides'
 run_fail $TEST_NAME.non-existent \
     cylc get-site-config --item='[this][doesnt]exist'
 #-------------------------------------------------------------------------------

diff --git a/tests/documentation/00-make.t b/tests/documentation/00-make.t
@@ -25,6 +25,6 @@ fi
 set_test_number 1
 #-------------------------------------------------------------------------------
 TEST_NAME=$TEST_NAME_BASE-make-docs
-run_ok $TEST_NAME make -C $CYLC_DIR/doc <'/dev/null'
+run_ok $TEST_NAME cylc make-docs <'/dev/null'
 #-------------------------------------------------------------------------------
 exit