From c46b53ba9bcc243f835a640cf4aa25cb0b8ccca9 Mon Sep 17 00:00:00 2001
From: Oliver Sanders <oliver.sanders@metoffice.gov.uk>
Date: Tue, 17 Oct 2023 17:32:37 +0100
Subject: [PATCH] user-guide: examples

* Document the major design patters for implementing Cylc workflows.
* Along with https://github.com/cylc/cylc-flow/pull/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.
---
 .gitignore                        |  1 +
 Makefile                          |  1 +
 bin/link-examples                 | 14 ++++++++++++++
 src/user-guide/examples/index.rst |  9 +++++++++
 src/user-guide/index.rst          |  1 +
 5 files changed, 26 insertions(+)
 create mode 100755 bin/link-examples
 create mode 100644 src/user-guide/examples/index.rst

diff --git a/.gitignore b/.gitignore
index b7f9ac14a9..9975c645e5 100644
--- a/.gitignore
+++ b/.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/*
diff --git a/Makefile b/Makefile
index b24452dc55..4cb1451f0d 100644
--- a/Makefile
+++ b/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
diff --git a/bin/link-examples b/bin/link-examples
new file mode 100755
index 0000000000..88361a2931
--- /dev/null
+++ b/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
+
diff --git a/src/user-guide/examples/index.rst b/src/user-guide/examples/index.rst
new file mode 100644
index 0000000000..9ae6b61cc5
--- /dev/null
+++ b/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
diff --git a/src/user-guide/index.rst b/src/user-guide/index.rst
index dca4eeb0ab..f81688b221 100644
--- a/src/user-guide/index.rst
+++ b/src/user-guide/index.rst
@@ -6,6 +6,7 @@ User Guide
    :maxdepth: 2
 
    introduction
+   examples/index
    writing-workflows/index
    installing-workflows
    running-workflows/index