conda builds (#293)

environment.yml files demonstrating possible conda installations

.github/workflows/conda-build-test.yml

@@ -0,0 +1,36 @@
+name: conda builds
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/conda-build-test.yml'
+      - 'src/reference/environments/*.ya?ml'
+  schedule:
+    - cron: '17 22 * * 6'
+  workflow_dispatch:
+
+jobs:
+  test_conda_install:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        case: [basic, gui, rose]
+        python: [3.7, 3.8, 3.9]
+    steps:
+      - name: checkout cylc-doc
+        uses: actions/checkout@v2
+
+      - name: build conda env ${{matrix.case}}
+        run: |
+          # Done like this so that we test all versions of python,
+          # and offer users examples of basic with all three versions
+          # but don't have to have three env.yml files for each case.
+          if [[ -f src/reference/environments/${{matrix.case}}-${{matrix.python}}.yml ]]; then
+            conda env create -f \
+              src/reference/environments/${{matrix.case}}-${{matrix.python}}.yml
+          else
+            conda env create -f \
+              src/reference/environments/${{matrix.case}}.yml \
+              python==${{matrix.python}}
+          fi

src/reference/environments/basic-3.7.yml

@@ -0,0 +1,7 @@
+name: cylc-8-basic-python-3.7
+# Cylc 8 without UI Server.
+channels:
+  - conda-forge
+dependencies:
+  - python=3.7
+  - cylc-flow=8.*

src/reference/environments/basic.yml

@@ -0,0 +1,7 @@
+name: cylc-8-basic
+# Cylc 8 without the UI Server.
+
+channels:
+  - conda-forge
+dependencies:
+  - cylc-flow=8.*

src/reference/environments/example_envs.rst

@@ -0,0 +1,43 @@
+Example Environments
+====================
+
+A set of example Conda Cylc Environments:
+
+.. csv-table::
+   :header:  environment, cylc, cylc uiserver, rose
+
+   `Cylc 8 basic`_, ✔️, ,
+   `Cylc 8 with UI Server`_, ✔️,✔️,
+   `Cylc 8 with Rose`_, ✔️,✔️,✔️
+
+Example installation commands:
+
+.. code-block:: bash
+
+   conda env create -f path/to/env.yml --name "name of env"
+
+
+Cylc 8 basic
+------------
+
+This environment contains the core workflow engine and shows how to specify a particular version of Python.
+
+.. literalinclude:: basic-3.7.yml
+   :language: YAML
+
+Cylc 8 with UI Server
+---------------------
+
+An environment containing the workflow engine and the GUI components.
+
+.. literalinclude:: gui.yml
+   :language: YAML
+
+Cylc 8 with Rose
+----------------
+
+In addition to the GUI components also add the Cylc-Rose plugin, and the
+Rose configuration management system.
+
+.. literalinclude:: rose.yml
+   :language: YAML

src/reference/environments/gui.yml

@@ -0,0 +1,7 @@
+name: cylc-8-with-gui
+# Cylc 8 and the also the UI Server (which provides the web GUI).
+channels:
+  - conda-forge
+dependencies:
+  - cylc-flow
+  - cylc-uiserver

src/reference/environments/rose.yml

@@ -0,0 +1,10 @@
+name: cylc-8-with-rose
+# Cylc 8, the UI Server (which provides the web GUI).
+# and the Cylc Rose plugin (which requires metomi-rose).
+channels:
+  - conda-forge
+dependencies:
+  - cylc-flow
+  - cylc-rose
+  - cylc-uiserver
+  - metomi-rose

src/reference/index.rst

@@ -7,4 +7,5 @@ Reference
 
    config/index
    api/index
+   environments/example_envs.rst
    dev-history-major-changes