user-guide: examples

* Document the major design patters for implementing Cylc workflows.
* Along with cylc/cylc-flow#5773, this closes #627
* Add some functional examples for users to play with.
* The aim is to help assist workflow writers by providing them with
  minimal templates to flush out.

Author: oliver-sanders

.gitignore

@@ -26,3 +26,4 @@ src/plugins/main-loop/built-in
 src/plugins/install/built-in
 src/user-guide/task-implementation/job-runner-handlers
 src/dictionaries/sentence_case
+src/user-guide/examples/*

Makefile

@@ -56,6 +56,7 @@ cleanall:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 # NOTE: EXPORT_ALL_VARIABLES exports make vars as env vars
 %: Makefile .EXPORT_ALL_VARIABLES
+	bin/link-examples
 	# build documentation
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	# write out dict of available versions and formats

bin/link-examples

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+set -eu
+
+# rm cylc-flow-examples || true
+examples="$(python -c 'import cylc.flow; from pathlib import Path; print(Path(cylc.flow.__file__).parent)')/etc/examples"
+for example in $(echo "${examples}/"*); do
+    if [[ -d "${example}" ]]; then
+        target="src/user-guide/examples/$(basename "${example}")"
+        rm "${target}" || true
+        ln -s "${example}" "${target}"
+    fi
+done
+

src/user-guide/examples/index.rst

@@ -0,0 +1,9 @@
+Examples
+========
+
+These examples cover some of the main patterns for implementing Cylc workflows.
+
+.. toctree::
+   :glob:
+
+   */index

src/user-guide/index.rst

@@ -6,6 +6,7 @@ User Guide
    :maxdepth: 2
 
    introduction
+   examples/index
    writing-workflows/index
    installing-workflows
    running-workflows/index