Merge branch 'master' into db-diagram

Author: hjoliver

.github/workflows/test_tutorial_workflow.yml

@@ -22,11 +22,33 @@ clean:
 	rm -rf src/plugins/install/built-in
 	rm -rf src/user-guide/task-implementation/job-runner-handlers
 
+watch: clean
+	# rebuild incrementally whenever documentation files are changed
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" \
+		--ignore='**plugins/main-loop/built-in/*.rst' \
+		--ignore='**plugins/install/built-in/*.rst' \
+		--ignore='**/job-runner-handlers/*.rst' \
+		--open-browser
+
+watch-cylc:
+	# rebuild non-incrementally (SLOW) whenever docs files OR Cylc source
+	# code files are changed
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" \
+		-a \
+		--pre-build='make clean' \
+		--ignore='**plugins/main-loop/built-in/*.rst' \
+		--ignore='**plugins/install/built-in/*.rst' \
+		--ignore='**/job-runner-handlers/*.rst' \
+		--watch="$(shell bin/c-locate cylc.flow)" \
+		--watch="$(shell bin/c-locate cylc.uiserver)" \
+		--watch="$(shell bin/c-locate cylc.rose)" \
+		--open-browser
+
 cleanall:
 	(cd doc; echo [0-9]*.*)
 	rm -rI doc/[0-9]*.*
 
-.PHONY: help clean Makefile .EXPORT_ALL_VARIABLES
+.PHONY: help clean watch Makefile .EXPORT_ALL_VARIABLES
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

Makefile

@@ -90,9 +90,56 @@ Note: you may need to install `graphviz` first (e.g. `conda install graphviz`).
 $ git clone [email protected]:cylc/cylc-doc.git cylc-doc
 $ cd cylc-doc
 $ pip install -e .
+```
+
+### Simple Build
+
+Build the docs using `make`:
+
+```console
 $ make html
 ```
 
+The documentation builds incrementally, if you make changes to the Cylc source
+files run `make clean`:
+
+```console
+$ make clean html
+```
+
+### Automatic Build
+
+You can also get Sphinx to rebuild automatically when documentation files are
+modified. Fist install the optional dependency `watch`:
+
+```console
+$ pip install -e .[watch]
+
+```
+
+Then build the `watch` target:
+
+```console
+$ make watch  # you do not need to `make clean` with the `watch` target
+```
+
+This will monitor for changes in the `cylc-doc` repository and rebuild the
+documentation incrementally.
+
+To also monitor for changes in the `cylc-flow`, `cylc-uiserver` and `cylc-rose`
+repositories use the `watch-cylc` target:
+
+```console
+$ make watch-cylc  # you do not need to `make clean` with the `watch` target
+```
+
+This forces a complete rebuild every time a file is changed which is slow, but
+allows it to pick up changes to autodocumented items in the source code.
+
+> **Note:** Your Cylc repositories must be installed in editible mode
+> i.e. `pip install -e <repo>` for this to work.
+> **Note:** This might not work for all filesystems.
+
 ### Testing
 
 ```console
@@ -149,7 +196,7 @@ preserved and does not require housekeeping.
 
 [![License](https://img.shields.io/github/license/cylc/cylc-doc.svg?color=lightgrey)](https://github.com/cylc/cylc-doc/blob/master/LICENSE)
 
-Copyright (C) 2008-<span actions:bind='current-year'>2021</span> NIWA & British Crown (Met Office) & Contributors.
+Copyright (C) 2008-<span actions:bind='current-year'>2022</span> NIWA & British Crown (Met Office) & Contributors.
 
 Cylc 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,

README.md

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env python
 # THIS FILE IS PART OF THE CYLC WORKFLOW ENGINE.
 # Copyright (C) NIWA & British Crown (Met Office) & Contributors.
 #
@@ -15,15 +15,25 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Locate Python repository installations."""
 
-set -eu
-cd "$(dirname "$0")"
+from pathlib import Path
+import sys
 
-for FILE in $(echo ../cylc/doc/etc/tutorial/*/.validate) ; do 
-    echo "running $FILE" 
-    (
-        cd "$(dirname "$FILE")"
-        ./.validate
-    ) 
-done
 
+def main(arg):
+    if arg == 'cylc.flow':
+        import cylc.flow
+        print(Path(cylc.flow.__file__).parent)
+    elif arg == 'cylc.uiserver':
+        import cylc.uiserver
+        print(Path(cylc.uiserver.__file__).parent)
+    elif arg == 'cylc.rose':
+        import cylc.rose
+        print(Path(cylc.rose.__file__).parent)
+    else:
+        raise ValueError(f'Unsupported arg: {arg}')
+
+
+if __name__ == '__main__':
+    main(sys.argv[1])

bin/run-validate renamed to bin/c-locate

@@ -34,7 +34,7 @@ DUMMY_FORMATS = [
 
 def get_versions(builddir):
     """Yield paths to each documented version."""
-    yield from pathlib.Path(builddir).glob('[0-9]*.*')
+    yield from pathlib.Path(builddir).glob('[0-9]*.[0-9]*')
     yield from pathlib.Path(builddir).glob('stable')
     yield from pathlib.Path(builddir).glob('latest')
     yield from pathlib.Path(builddir).glob('nightly')