Cylc Tutorial

.eslintignore

@@ -0,0 +1,2 @@
+doc/[0-9]*.*
+doc/current

.eslintrc.json

@@ -0,0 +1,11 @@
+{
+    "extends": "eslint:recommended",
+    "parserOptions": {
+        "ecmaVersion": 6
+    },
+    "env": {
+        "browser": true,
+        "es6": true,
+        "jquery": true
+    }
+}

.travis.yml

@@ -37,12 +37,15 @@ env:
     - PATH="${TRAVIS_BUILD_DIR}/bin:$PATH"
 
 install:
+  - sudo apt-get install -y graphviz
   - pip install git+https://github.com/cylc/cylc-flow/
   - pip install -e .'[all]'
+  - npm install -g eslint
 
 script:
   - pycodestyle
-  - make html singlehtml linkcheck SPHINXOPTS='-W'
+  - eslint .
+  - make html singlehtml slides linkcheck SPHINXOPTS='-W'
 
 after_failure:
   - cat /tmp/sphinx-err*  # sphinx traceback

Makefile

@@ -2,7 +2,7 @@
 
 # You can set these variables from the command line:
 # e.g. $ make html CYLC_VERSION=1.2.3
-CYLC_VERSION = $(shell cylc version)
+CYLC_VERSION = $(shell cylc version | sed 's/Cylc Flow //')
 SPHINXOPTS =
 SPHINXBUILD = sphinx-build
 SOURCEDIR = src
@@ -30,7 +30,7 @@ cli:
 %: Makefile cli
 	# build documentation
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-	# write out dict of availabe versions and formats
-	bin/write-version-file doc/versions.json
+	# write out dict of available versions and formats
+	bin/write-version-file > doc/versions.json
 	# setup HTML redirects to point at this version
 	bin/set-default-path "$(CYLC_VERSION)" html

bin/write-version-file

@@ -17,7 +17,6 @@
 
 import json
 import pathlib
-import sys
 
 
 DUMMY_FORMATS = [
@@ -42,13 +41,11 @@ def get_formats():
 
 def main():
     """Write documentation versions and formats to JSON file."""
-    try:
-        filename = sys.argv[1]
-    except IndexError:
-        sys.exit(__doc__)
-    json.dump(
-        get_formats(),
-        open(filename, 'w+')
+    print(
+        json.dumps(
+            get_formats(),
+            indent=4
+        )
     )
 
 

doc/versions.js

@@ -0,0 +1,89 @@
+/* global CUR_VERSION, ROOT_DIR, PAGE_NAME, CUR_FORMAT */
+// these variables come from versions.html in the Sphinx theme
+
+$('#versions-and-formats')
+    .append(
+        $('<span />')
+            .addClass('rst-current-version')
+            .attr({'data-toggle': 'rst-current-version'})
+            .append(
+                $('<span />')
+                    .addClass('fa fa-book')
+                    .append('Versions'),
+                $('<span />').append('v: ' + CUR_VERSION),
+                $('<span />')
+                    .addClass('fa fa-caret-down')
+            ),
+        $('<div />')
+            .addClass('rst-other-versions')
+            .attr({'id': 'versions'})
+            .append(
+                $('<h4 />')
+                    .append('Versions')
+            ),
+        $('<div />')
+            .addClass('rst-other-versions')
+            .attr({'id': 'formats'})
+            .append(
+                $('<h4 />')
+                    .append('Formats')
+            )
+    )
+
+// path to JSON file with versions and formats dictionary
+const VERSIONS_URL = ROOT_DIR + '/versions.json';
+
+function url(version, format) {
+    // return the URL of the curret page in the documentation
+    var ret = ROOT_DIR + '/' + version + '/' + format + '/';
+    if (format === 'html') {
+        ret += PAGE_NAME + '.html';
+    } else if (format === 'singlehtml') {
+        ret += 'index.html#document-' + PAGE_NAME;
+    } else if (format === 'epub') {
+        ret += 'Cylc.epub';
+    } else if (format == 'latex') {
+        ret += 'cylc.pdf'
+    } else {
+        ret += 'index.html';
+    }
+    return ret
+}
+
+$(document).ready(function() {
+    const version_div = $('#versions');
+    const format_div = $('#formats')
+
+    $.ajax({
+        'type': 'GET',
+        'url': VERSIONS_URL,
+        dataType: 'json',
+        success: function (versions) {
+            // write list versions (for all formats)
+            var vn_fmt;
+            for (let version of Object.keys(versions).sort()) {
+                if (versions[version].indexOf(CUR_FORMAT) === -1) {
+                    vn_fmt = 'html';  // fallback to html
+                } else {
+                    vn_fmt = CUR_FORMAT;  // link current format
+                }
+                version_div.append(
+                    $('<a />')
+                        .attr({'href': url(version, vn_fmt)})
+                        .css({'padding-left': '1em'})
+                        .append(version)
+                );
+            }
+
+            // write formats for current version
+            for (let format of versions[CUR_VERSION]) {
+                format_div.append(
+                    $('<a />')
+                        .attr({'href': url(CUR_VERSION, format)})
+                        .css({'padding-left': '1em'})
+                        .append(format)
+                );
+            }
+        }
+    });
+});

setup.py

@@ -23,6 +23,9 @@
 
 INSTALL_REQUIRES = [
     'sphinx==2.0.*',
+    'sphinx_rtd_theme',
+    'sphinxcontrib-svg2pdfconverter',
+    'hieroglyph'
 ]
 
 EXTRAS_REQUIRE = {

src/_static/css/cylc.css

@@ -0,0 +1,140 @@
+.logo {
+    height: 110px!important;
+    /* Read the docs theme can't handle vector medium.
+     * Image will not overflow width, so just give a sensible height value. */
+}
+
+/* Correct the behaviour of the read the docs theme which greedily overrides
+ * sphinx's `pygments_style` option by placing its own syntax in the
+ * stylesheet - https://github.com/rtfd/sphinx_rtd_theme/issues/166 */
+.highlight * {
+    color: black;
+    font-weight: normal;
+    font-style: normal;
+    background-color: transparent;
+}
+
+/* Correct the behaviour of nested admonitions. Sometimes the admonition-header
+ * inherits its parents styling. */
+.rst-content .error .admonition-title, .rst-content .danger .admonition-title {
+    background: red
+}
+.rst-content .warning .admonition-title,
+.rst-content .caution .admonition-title,
+.rst-content .attention .admonition-title {
+    background: orange
+}
+
+/* Enable theme handling of pilcrow symbols for code-block captions and
+ * admonitions. */
+.rst-content p.admonition-title .pull-left.headerlink,
+.rst-content div.code-block-caption .pull-left.headerlink {
+    margin-right:.3em
+}
+.rst-content p.admonition-title .pull-right.headerlink,
+.rst-content div.code-block-caption .pull-right.headerlink {
+    margin-left:.3em
+}
+.rst-content p.admonition-title .headerlink:before,
+.rst-content div.code-block-caption .headerlink:before {
+    font-family:"FontAwesome";
+    display:inline-block;
+    font-style:normal;
+    font-weight:normal;
+    line-height:1;
+    text-decoration:inherit;
+    font-size:14px;
+    vertical-align:-15%;
+    -webkit-font-smoothing:antialiased
+}
+.rst-content p.admonition-title .headerlink:after,
+.rst-content div.code-block-caption .headerlink:after {
+    visibility:visible;
+    content:"";
+    font-family:FontAwesome;
+    display:inline-block;
+    color:#2980B9
+}
+.rst-content p.admonition-title:hover .headerlink,
+.rst-content div.code-block-caption:hover .headerlink {
+    display:inline-block
+}
+.rst-content p.admonition-title .headerlink,
+.rst-content div.code-block-caption .headerlink {
+    font:normal normal normal 14px/1 FontAwesome;
+    text-rendering:auto;
+    -webkit-font-smoothing:antialiased;
+    -moz-osx-font-smoothing:grayscale;
+    display:none;
+    visibility:hidden;
+    color:#fcfcfc;
+    text-decoration:inherit
+}
+
+/* Fix the lack of space underneath lists inside admonitions. */
+.rst-content div.admonition ul,
+.rst-content div.admonition ol > li {
+    padding-bottom: 0.5em;
+}
+
+/* Add warning symbol before deprecated items. */
+.deprecated p:before {
+    font-family:FontAwesome;
+    content:"\f071  ";
+    color: rgb(200, 90, 70);
+}
+
+.deprecated p span.versionmodified{
+    font-weight: bold;
+}
+
+/* Implement grid-table class for plain style grid layouts. */
+.grid-table {
+    width: 100% !important;
+    border: 0 !important; /* Remove table border. */
+}
+.grid-table tbody tr td:first-child {
+    padding-left: 0 !important; /* Grid flush with the left-hand content edge. */
+}
+.grid-table tbody tr td:last-child {
+    padding-right: 0 !important; /* Grid flush with the right-hand edge */
+}
+.grid-table tbody tr td {
+    background-color: rgba(255,255,255,0) !important;
+    border: 0 !important;  /* Remove cell border. */
+    vertical-align: top !important;  /* All content should float to the top. */
+}
+.grid-table td {
+    /* docutils sticks tables inside an align-center class, correct this */
+    text-align: left;
+}
+
+/* Tables handle their own margin, this prevents getting a double margin. */
+.grid-table div.highlight {
+    margin-bottom: 0;
+}
+
+/* Place code-block captions in italics. */
+.code-block-caption {
+    font-style: italic;
+    color: #808080;
+}
+
+/* Block an element from being included in text selections. */
+.noselect {
+    -webkit-user-select: none;
+     -khtml-user-select: none;
+       -moz-user-select: none;
+        -ms-user-select: none;
+            user-select: none;
+}
+
+/* Extension to Pygments to insert the "added" and "unchanged" characters in
+ * a "diff" code block using CSS so that they aren't included when copied as
+ * text. */
+.highlight-diff .gi:before {
+    content: '+';
+}
+.highlight-diff .gn:before {
+    content: ' ';
+}

src/_static/css/slides-custom.css

@@ -0,0 +1,31 @@
+/* Make quotations small enough to fit on the slide. */
+q {
+    font-size: 1em;
+}
+
+/* Add a bit of space between slide titles and images. */
+object, img {
+    margin: 1em 0 1em 0;
+}
+
+/* Don't display glossary terms as hyperlinks. */
+a.reference {
+    text-decoration: none
+}
+a.reference span.std {
+    text-decoration: underline;   
+}
+a.reference span.xref {
+    text-decoration: none;
+    color: #909090;
+    font-style: italic;
+}
+a.reference span.xref:hover {
+    text-decoration: underline;   
+    color: #0066CC;
+}
+
+/* Make code block captions legible. */
+.code-block-caption span {
+    font-size: 2em;
+}