Merge pull request #342 from oliver-sanders/8.0b3-installation-changes

8.0b3 installation changes

.github/actions/create-conda-envs/action.yml

@@ -0,0 +1,50 @@
+name: Build Conda Envs
+description: Create Conda environments from documented env files.
+
+inputs:
+  python_version:
+    description: Version to install.
+    required: true
+  cylc_flow_version:
+    description: Version to install.
+    required: false
+
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      run: |
+        # get cylc version...
+        if [[ -z '${{ inputs.cylc_flow_version }}' ]]; then
+          # ... from cylc library
+          CYLC_RELEASE="$(python src/lib/cylc_release.py)"
+        else
+          # ... from GitHub action input
+          CYLC_RELEASE="${{ inputs.cylc_flow_version }}"
+        fi
+        echo "CYLC_RELEASE=$CYLC_RELEASE" >> "${GITHUB_ENV}"
+
+    - shell: bash
+      run: |
+        # use mamba (much faster)
+        # use this when released: https://github.com/mamba-org/setup-mamba
+        conda install -n base -c conda-forge -y mamba
+
+    - shell: bash
+      run: |
+        for env_file in $(echo src/reference/environments/envs/*.yml); do
+        echo "# creating env from: ${env_file}"
+          new_env_file="$(sed 's/\(.*\)\.yml/\1-2.yml/' <<< "${env_file}")"
+          # substitute the python and cylc-flow versions in the env files
+          # TODO: add explicit python dep
+          sed \
+            -e 's/python =.*/python =${{ inputs.python_version }}/' \
+            -e "s/|release|/${CYLC_RELEASE}/" \
+            "${env_file}" \
+            > "${new_env_file}"
+          # create the env
+          conda run -n base mamba env create -f "${new_env_file}" -n cylc-env
+          # test the env
+          conda run -n cylc-env cylc version
+          conda env remove -n cylc-env
+        done

.github/workflows/create-conda-envs.yml

@@ -0,0 +1,48 @@
+name: create conda environments
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/create-conda-envs.yml'
+      - 'src/reference/environments/env/*.ya?ml'
+  workflow_dispatch:
+    inputs:
+      cylc_flow_version:
+        description: 'Version to install.'
+        required: true
+
+jobs:
+  test_conda_install:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      matrix:
+        python: [3.7, 3.8, 3.9]
+    steps:
+      - name: checkout cylc-doc
+        uses: actions/checkout@v2
+
+      - name: configure python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.7'
+
+      - name: install
+        run: |
+          # pick up deps for version processing
+          pip install 'setuptools>=49'
+
+      - name: checkout cylc-flow init file
+        run: |
+          # needed to extract the cylc-flow version
+          LIB_PATH='src/lib/cylc/flow'
+          mkdir -p "$LIB_PATH"
+          curl \
+            https://raw.githubusercontent.com/cylc/cylc-flow/master/cylc/flow/__init__.py \
+            > "$LIB_PATH/__init__.py"
+
+      - name: create conda envs
+        uses: ./.github/actions/create-conda-envs
+        with:
+          python_version: ${{ matrix.python }}
+          cylc_flow_version: ${{ github.event.inputs.cylc_flow_version }}

.github/workflows/deploy.yml

@@ -46,6 +46,10 @@ on:
         type: boolean
         default: true
         required: false
+      skip_conda_environment_check:
+        description: "Don't fail if the conda environments fail to build."
+        type: boolean
+        default: false
 
 jobs:
   deploy:
@@ -85,6 +89,12 @@ jobs:
           git clone --depth 1 --branch "${meto_rose}" https://github.com/metomi/rose ../rose
           pip install -e ../rose[all]
 
+      - name: create conda envs
+        uses: ./.github/actions/create-conda-envs
+        continue-on-error: ${{ github.event.inputs.skip_conda_environment_check }}
+        with:
+          python_version: '3.7'
+
       - name: checkout gh-pages
         uses: actions/checkout@v2
         with:

Makefile

@@ -1,12 +1,11 @@
 # Minimal makefile for Sphinx documentation
 
 # You can set these variables from the command line:
-# e.g. $ make html CYLC_VERSION=1.2.3
-CYLC_VERSION = $(shell cylc version | sed 's/Cylc Flow //')
+# e.g. $ make html SPHINXOPTS=-W
 SPHINXOPTS = -n
 SPHINXBUILD = sphinx-build
 SOURCEDIR = src
-BUILDDIR = doc/$(CYLC_VERSION)
+BUILDDIR = doc/$(shell cylc version)
 STABLE = true  # Makes this the Stable and default build
 LATEST = true  # Makes this the Latest build
 # The Stable/default build is what you get when navigating to the docs root dir

setup.py

@@ -39,9 +39,10 @@ def get_version(module, path):
 )
 
 INSTALL_REQUIRES = [
-    'cylc-sphinx-extensions>=1.3.2',
+    'cylc-sphinx-extensions>=1.3.3',
     'eralchemy==1.2.*',
     'hieroglyph>=2.1.0',
+    'setuptools>=49',
     'sphinx>=3.0.0',
     'sphinx_rtd_theme>=0.5.0',
     'sphinxcontrib-svg2pdfconverter',

src/conf.py

@@ -15,8 +15,14 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 from distutils.spawn import find_executable as which
-import sys
 import os
+import sys
+
+from cylc.flow import __version__ as CYLC_VERSION
+
+sys.path.append(os.path.abspath('lib'))  # path to lib.
+
+from cylc_release import CYLC_RELEASE
 
 
 # -- General configuration ------------------------------------------------
@@ -44,6 +50,7 @@
     'cylc.sphinx_ext.practical',
     'cylc.sphinx_ext.rtd_theme_addons',
     'cylc.sphinx_ext.sub_lang',
+    'cylc.sphinx_ext.literal_sub_include',
 ]
 
 rst_epilog = open('hyperlinks.rst.include', 'r').read()
@@ -84,8 +91,9 @@
 )
 
 # Versioning information.
-release = os.environ['CYLC_VERSION']  # set in makefile
-version = '.'.join(release.split('.')[:2])  # short version for display
+# NOTE: Sphinx considers version/release the other way around to us
+release = CYLC_VERSION  # full version e.g. "8.0.0"
+version = CYLC_RELEASE  # short version (for pinning / display) e.g. "8.0"
 
 # Autosummary opts (for auto generation of docs from source code).
 autosummary_generate = True
@@ -213,3 +221,8 @@
 
 # How to display URL addresses.
 texinfo_show_urls = 'footnote'
+
+literal_sub_include_subs = {
+    'version': version,
+    'release': release.replace('.dev', ''),
+}

src/hyperlinks.rst.include

@@ -6,7 +6,9 @@
 .. _Cylc User Guide: https://cylc.github.io/cylc-doc/latest/html/index.html
 .. _Cylc Workflow Design Guide: https://cylc.github.io/cylc-doc/latest/html/workflow-design-guide/index.html
 .. _Cylc: https://cylc.github.io/
+.. _Cylc 8 Discourse Support Group: https://cylc.discourse.group/c/cylc/7-to-8/13
 .. _DataPoint: https://www.metoffice.gov.uk/services/data/datapoint
+.. _Discourse: https://cylc.discourse.group/
 .. _EmPy: http://www.alcyone.com/software/empy/
 .. _FCM User Guide: http://metomi.github.io/fcm/doc/user_guide/
 .. _FCM: https://metomi.github.io/fcm/doc/

src/installation.rst

@@ -3,64 +3,53 @@
 Installation
 ============
 
-.. warning::
-
-   Cylc 8.0b3 is the final *beta release* of Cylc 8, a major upgrade from Cylc 7.
+.. note::
 
-   All Cylc 8 system components are in place but not yet heavily tested by users. 
-   Cylc 7 is still available if needed.
+   Cylc |release| is a pre release not recommended for production use.
 
-   This documentation has been revised for Cylc 8, but some new features are
-   yet to be fully described.
+   Please report any issues to the `Cylc 8 Discourse Support Group`_.
 
 
 Quick Installation
 ------------------
 
-Cylc runs on Unix systems including Linux and Mac OS.
-
-.. highlight:: sub
-
-.. list-table::
-   :class: grid-table
-
-   * - .. rubric:: Via Conda (recommended):
-     - .. rubric:: Via Pip (+npm):
+Cylc runs on Unix-like systems including Linux and Mac OS.
 
-   * - ::
+Via Conda (recommended)
+^^^^^^^^^^^^^^^^^^^^^^^
 
-          $ conda install cylc-flow
+.. code-block:: sub
 
-          # install the browser-GUI (optional)
-          $ conda install cylc-uiserver
+   $ conda install -c conda-forge cylc-flow
 
-          # install Rose support (optional)
-          $ conda install cylc-rose
+   # install the browser-GUI (optional)
+   $ conda install -c conda-forge cylc-uiserver
 
-     - ::
+   # install Rose support (optional)
+   $ conda install -c conda-forge cylc-rose metomi-rose
 
-          $ pip install cylc-flow
+Via Pip (+npm)
+^^^^^^^^^^^^^^
 
-          # install the browser-GUI (optional)
-          # (requires nodejs & npm)
-          $ pip install cylc-uiserver
-          $ npm install configurable-http-proxy
+.. note::
 
-          # install Rose support (optional)
-          $ pip install cylc-rose
+   Requires Python 3.7+
 
-   * -
-     -
-       .. note::
+.. note::
 
-          Requires Python 3.7+
+   We recommend using a virtual environment.
 
-       .. note::
+.. code-block:: sub
 
-          We recommend using a virtual environment.
+   $ pip install cylc-flow
 
+   # install the browser-GUI (optional)
+   # (requires nodejs & npm)
+   $ pip install cylc-uiserver
+   $ npm install configurable-http-proxy
 
-.. highlight:: bash
+   # install Rose support (optional)
+   $ pip install cylc-rose metomi-rose
 
 
 .. _non-python-requirements:
@@ -78,7 +67,7 @@ These dependencies are not installed by Conda or pip:
 
 These dependencies are installed by Conda but not by pip (you can use npm):
 
-* `configurable-http-proxy`_
+* `configurable-http-proxy`_ (optional: for multi-user setups)
 
 
 Installing On Mac OS
@@ -90,9 +79,9 @@ Installing On Mac OS
 Cylc requires some extra packages to function on Mac OS, we recommend
 installing them using the `Homebrew`_ package manager:
 
-.. code-block::
+.. code-block:: console
 
-   brew install bash coreutils gnu-sed
+   $ brew install bash coreutils gnu-sed
 
 You will need to prepend the ``coreutils`` and ``gnu-sed`` installations to
 your ``$PATH``, follow the instructions in the ``brew install`` output.
@@ -119,16 +108,21 @@ your ``$PATH``, follow the instructions in the ``brew install`` output.
    for instructions on enabling SSH.
 
 
-Site Installation
------------------
+Advanced Installation
+---------------------
+
+For distributed and multi-user installation we recommend using Conda and
+installing Cylc components only where required.
 
-For multi-user installation we recommend using Conda and installing
-Cylc components only where required.
+.. tip::
 
-The Cylc Packages
-^^^^^^^^^^^^^^^^^
+   For examples of Conda environments and installation options see
+   :ref:`conda environments` for examples and details.
 
-Cylc is split into a number of packages providing different functionality:
+The Cylc Components
+^^^^^^^^^^^^^^^^^^^
+
+Cylc is split into a number of components providing different functionality:
 
 `Cylc Flow`_
    Provides the scheduler "kernel" of Cylc along with the command line interface.
@@ -187,6 +181,7 @@ environment before calling the environment's  ``cylc`` command.
    This should be installed somewhere in the system search ``$PATH`` such
    as ``/usr/local/bin``.
 
+
 Configuration
 -------------