Docs (User + Design Guides) conversion to Sphinx

.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

bin/cylc-check-software

@@ -55,20 +55,11 @@ opt_spec = {
     'requests': [(2, 4, 2), 'HTTPSCOMMS', 'PY'],
     'OpenSSL': [None, 'HTTPSCOMMS', 'PY'],
     'urllib3': [None, 'HTTPSCOMMS', 'PY'],
+    'sphinx': [(1, 5, 3), 'HTMLDOCS', 'PY'],
     'pygtk': [(2, 0), 'GUIORGRAPH', 'PY'],
     'pygraphviz': [None, 'GUIORGRAPH', 'PY'],
-    'texlive': [None, 'LATEXGUIDE', 'TEX'],
-    'tocloft': [None, 'LATEXGUIDE', 'TEX'],
-    'framed': [None, 'LATEXGUIDE', 'TEX'],
-    'preprint': [None, 'LATEXGUIDE', 'TEX'],
-    'tex4ht': [None, 'LATEXGUIDE', 'TEX'],
-    'TeX': [(3, 0), 'LATEXGUIDE', 'OTHER',
-            (['tex'], '-v', r'TeX ([^\s]+)')],
     'graphviz': [None, 'GUIORGRAPH', 'OTHER',
                  (['dot'], '-V', r'graphviz version ([^\s]+)', 2)],
-    'ImageMagick': [None, 'HTMLUGUIDE', 'OTHER',
-                    (['magick convert', 'convert'],
-                     '-version', r'ImageMagick ([^\s]+)')]
 }
 
 # All possible module reqs to accept as arguments, as above or all lower case.
@@ -81,8 +72,7 @@ func_tags_and_text = {
     'TEMPLATING': 'configuration templating',
     'HTTPSCOMMS': 'HTTPS communications layer',
     'GUIORGRAPH': 'GUI & dependency graph visualisation',
-    'LATEXGUIDE': 'LaTeX User Guide',
-    'HTMLUGUIDE': 'HTML User Guide'
+    'HTMLDOCS': 'HTML documentation',
 }
 
 # Initialise results dict

bin/cylc-documentation

@@ -18,7 +18,7 @@
 
 """cylc [info] documentation|browse [OPTIONS] [SUITE]
 
-View documentation in browser or PDF viewer, as per Cylc global config.
+View documentation in the browser, as per Cylc global config.
 
 % cylc doc [OPTIONS]
    View local or internet [--www] Cylc documentation URLs.
@@ -53,8 +53,9 @@ def main():
     parser = OptionParser(__doc__)
 
     parser.add_option(
-        "-p", "--pdf", help="Open the PDF User Guide directly.",
-        action="store_true", default=False, dest="pdf")
+        "-g", "--guides",
+        help="Open the HTML (User & Suite Design) Guides directly.",
+        action="store_true", default=False, dest="guides")
 
     parser.add_option(
         "-w", "--www", help="Open the cylc internet homepage",
@@ -96,16 +97,13 @@ def main():
     intranet_url = glbl_cfg().get(['documentation', 'urls', 'local index'])
     internet_url = glbl_cfg().get(['documentation', 'urls',
                                    'internet homepage'])
-    html_file = glbl_cfg().get(['documentation', 'files', 'html index'])
+    html_file = glbl_cfg().get(['documentation', 'files', 'html user guides'])
     html_viewer = glbl_cfg().get(['document viewers', 'html'])
-    pdf_file = glbl_cfg().get(['documentation', 'files', 'pdf user guide'])
-    pdf_viewer = glbl_cfg().get(['document viewers', 'pdf'])
     if len(args) == 0:
         # Cylc documentation.
-        if options.pdf:
-            # Force PDF.
-            viewer = pdf_viewer
-            target = pdf_file
+        if options.guides:
+            viewer = html_viewer
+            target = html_file
         elif options.url:
             viewer = html_viewer
             target = options.url
@@ -129,9 +127,9 @@ def main():
 
     elif len(args) == 1:
         # Suite or task documentation.
-        if options.pdf or options.www:
-            print >> sys.stderr, (
-                "(Note: --pdf and --www are ignored for suite documentation).")
+        if options.guides or options.www:
+            print >> sys.stderr, ("(Note: --guides and --www are ignored for "
+                "suite documentation).")
         suite = args[0]
         if options.task_name:
             # Task documentation.
@@ -156,7 +154,7 @@ def main():
     else:
         parser.error("Too many arguments.")
 
-    if target in [pdf_file, html_file] and not os.path.isfile(target):
+    if target in html_file and not os.path.isfile(target):
         sys.exit("ERROR, file not found: %s (see your cylc admin)" % target)
 
     # viewer may have spaces (e.g. 'firefox --no-remote'):

bin/cylc-help

@@ -294,6 +294,7 @@ admin_commands['profile-battery'] = ['profile-battery']
 admin_commands['import-examples'] = ['import-examples']
 admin_commands['upgrade-run-dir'] = ['upgrade-run-dir']
 admin_commands['check-software'] = ['check-software']
+admin_commands['make-docs'] = ['make-docs']
 
 license_commands = {}
 license_commands['warranty'] = ['warranty']
@@ -365,6 +366,7 @@ comsum['profile-battery'] = 'Run a battery of profiling tests'
 comsum['import-examples'] = 'Import example suites your suite run directory'
 comsum['upgrade-run-dir'] = 'Upgrade a pre-cylc-6 suite run directory'
 comsum['check-software'] = 'Check required software is installed'
+comsum['make-docs'] = 'Build the HTML documentation with Sphinx.'
 # license
 comsum['warranty'] = 'Print the GPLv3 disclaimer of warranty'
 comsum['conditions'] = 'Print the GNU General Public License v3.0'

bin/cylc-make-docs

@@ -0,0 +1,52 @@
+#!/bin/bash
+#
+# Copyright (C) 2008-2018 NIWA & British Crown (Met Office) & Contributors.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+usage() {
+    echo "Usage: cylc [admin] make-docs [--help]"
+    echo "This command builds the HTML documentation, which is auto-generated"
+    echo "with the tool Sphinx. It wraps the 'sphinx-build' command."
+    echo ""
+    echo "Options:"
+    echo "  --help   Print this usage message."
+}
+
+if [[ $# != 0 ]]; then
+    usage
+    if [[ $1 == "--help" ]]; then
+        exit 0
+    else
+        echo "ERROR: illegal command line arguments"
+        exit 1
+    fi
+fi
+
+echo >&2
+echo "Building the HTML Cylc Documentation with Sphinx:"
+echo >&2
+cd "$CYLC_DIR"/doc/
+echo "... Generating the command reference ..."
+./src/custom/make-commands.sh
+echo >&2
+
+# Determine the Cylc version to pass through to the conf.py ('-D' option below)
+# TODO: when Cylc is a package, instead fetch '__version__' within the conf.py
+CYLC_VER=$(cylc --version)
+echo "... Auto-generating the HTML with Sphinx ..."
+sphinx-build -D version=${CYLC_VER} -D release=${CYLC_VER} \
+    -n -b html ./src built-sphinx/
+echo >&2
+echo "Done."