Merge pull request #381 from oliver-sanders/autobuild

make: Add sphinx-autobuild support

Author: hjoliver

Makefile

@@ -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).

README.md

@@ -86,9 +86,56 @@ We use a few custom Sphinx extensions, for details see
 $ 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

bin/c-locate

@@ -0,0 +1,39 @@
+#!/usr/bin/env python
+# THIS FILE IS PART OF THE CYLC WORKFLOW ENGINE.
+# Copyright (C) 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/>.
+
+"""Locate Python repository installations."""
+
+from pathlib import Path
+import sys
+
+
+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])

setup.py

@@ -59,7 +59,9 @@ def get_version(module, path):
         'flake8-mutable>=1.2.0',
         'flake8-simplify>=0.14.0',
     ],
-
+    'watch': [
+        'sphinx-autobuild',
+    ],
 }
 EXTRAS_REQUIRE['all'] = [y for x in EXTRAS_REQUIRE.values() for y in x]