Merge branch 'docs-update' into 'master'

Document available environments using latest container

See merge request !10

.gitlab-ci.yml

@@ -4,6 +4,8 @@ image: docker:latest
 stages:
   - test
   - build
+  - docs
+  - deploy
 
 variables:
   DOCKER_DRIVER: overlay
@@ -19,13 +21,12 @@ test:
   only:
     - merge_requests
   script:
-    - docker build --pull --tag test --build-arg INSTALL_PATH=/opt/conda .
+    - docker build --pull --tag ${CI_REGISTRY_IMAGE}:test --build-arg INSTALL_PATH=/opt/conda .
 
 build-latest:
   stage: build
   only:
     - master
-    - schedules
   script:
     - docker build --no-cache --pull -t $TAG --build-arg INSTALL_PATH=/cvmfs/ligo-containers.opensciencegrid.org/${CI_PROJECT_NAMESPACE}/${CI_PROJECT_NAME}/latest .
     - docker push $TAG
@@ -41,17 +42,19 @@ build-nightly:
 # -- documentation
 
 docs:
-  stage: test
-  image: python:3.7
+  stage: docs
+  image: $TAG
+  dependencies:
+    - build-latest
   only:
-    - branches
-    - tags
-    - merge_requests
-  before_script:
-    - python -m pip install -r docs/requirements.txt
+    - master
   script:
+    - CONDA_BASE="/cvmfs/ligo-containers.opensciencegrid.org/lscsoft/conda/latest"
+    - PYTHON=${CONDA_BASE}/bin/python
+    - source ${CONDA_BASE}/etc/profile.d/conda.sh
+    - ${PYTHON} -m pip install -r docs/requirements.txt --user
     - cd docs
-    - python -m sphinx -M html . ../build/sphinx
+    - ${PYTHON} -m sphinx -M html . ../build/sphinx
   artifacts:
     paths:
       - build/sphinx/html
@@ -60,7 +63,7 @@ docs:
       - .cache/pip
 
 pages:
-  stage: build
+  stage: deploy
   dependencies:
     - docs
   only:

docs/conf.py

@@ -41,6 +41,7 @@ release = ''
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinxcontrib.programoutput',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/environments/index.rst

 ======================
-Pre-built environments
+Reference environments
 ======================
 
-The LSCSoft Conda team currently provides pre-defined environments for a number
+The LSCSoft Conda team currently defines reference environments for a number
 of version of Python.
 You can install these by downloading the relevant YAML file from the repository
 and installing them.
 
+----------------------
+Pre-built environments
+----------------------
+
+The reference environments are pre-built and distributed using
+`CVMFS <https://cvmfs.readthedocs.io/>`_.
+You can configure your system to use the distributed conda installation:
+
+.. code-block:: bash
+
+   source /cvmfs/ligo-containers.opensciencegrid.org/lscsoft/conda/latest/etc/profile.d/conda.sh
+
+You can then list the available environments:
+
+.. code-block:: bash
+
+   conda env list
+
+which will print something like:
+
+.. program-output:: conda env list
+
+You can then activate one of these environments:
+
+.. code-block:: bash
+
+   conda activate ligo-py37
+
+----------------------
+Available environments
+----------------------
+
 .. toctree::
-   :caption: Available environments
    :glob:
 
-   environment*
+   *

docs/requirements.txt

@@ -2,3 +2,4 @@ sphinx
 sphinx_rtd_theme
 astropy
 pyyaml
+sphinxcontrib-programoutput

docs/utils.py

@@ -3,9 +3,11 @@
 """Format the current list of environments for inclusion in the sphinx docs
 """
 
+import json
 import os.path
 import pathlib
 import re
+from subprocess import check_output
 
 import yaml
 
@@ -13,28 +15,30 @@ from astropy.table import Table
 
 
 def find_environments(path=None):
-    """Finds all of the environment.yml files under the given path
+    """Finds all of the environments known to conda
     """
+    # get files
     if path is None:
-        path = pathlib.Path(_file_).resolve().parent.parent
-    yield from path.glob('environment-*.yml')
+        path = pathlib.Path(__file__).resolve().parent.parent
+    files = path.glob('environment-*.yml')
 
+    # get environments
+    envs = json.loads(check_output([
+        'conda',
+        'env',
+        'list',
+        '--json',
+        '--quiet',
+    ]).strip().decode())['envs']
+    env_names = [pathlib.Path(env).name for env in envs]
 
-def list_environments(path=None, file=None):
-    yamls = find_environments(path=path)
-    for yaml in map(os.path.basename, yamls):
-        print(
-            "* `{0} <https://git.ligo.org/lscsoft/conda/raw/master/"
-                "{0}>`_".format(yaml),
-            file=file,
-        )
-
-
-def pinned_version(spec):
-    match = re.search(r"\A[a-zA-Z0-9_\s]+=", spec)
-    if match:
-        return spec[match.end():].strip()
-    return None
+    # cross-check
+    for fn in files:
+        with fn.open("rb") as envf:
+            content = yaml.load(envf)
+            name = content['name']
+            if name in env_names:
+                yield fn
 
 
 def write_environment(env, file=None):
@@ -63,39 +67,32 @@ def write_environment(env, file=None):
           "   conda env create --file {0}\n".format(env.name),
           file=file)
 
+    # get packages
+    celist = check_output([
+        'conda',
+        'list',
+        '--name',
+        name,
+        '--json',
+        '--quiet',
+    ])
+    packages = json.loads(celist)
+
     # write packages
     print("| **Packages:**\n", file=file)
     rows = []
     images = {}
-    for pkg in content['dependencies']:
-        pname = re.split("[>=]", pkg)[0].strip()
-        version = pinned_version(pkg)
+    for pkg in packages:
+        cloudchannel = ('anaconda' if pkg['channel'] == 'pkgs/main' else
+                        pkg['channel'])
         rows.append((
-            "`{0} <https://anaconda.org/conda-forge/{0}/>`_".format(pname),
-            "|{0}-version|".format(pname),
-            "|{0}-platform|".format(pname),
+            "`{name} <https://anaconda.org/{cloudchannel}/{name}/>`_".format(
+                cloudchannel=cloudchannel,
+                **pkg
+            ),
+            pkg['version'],
+            pkg['build_string'],
+            pkg['channel'],
         ))
-        if version:
-            colour = "orange" if version.startswith("0.") else "blue"
-            images["{0}-version".format(pname)] = (
-                "https://img.shields.io/badge/conda--forge-v{0}-{1}.svg".format(
-                    version, colour,
-                ),
-                "{0} version on conda-forge".format(pname),
-            )
-        else:
-            images["{0}-version".format(pname)] = (
-                "https://img.shields.io/conda/vn/conda-forge/{0}.svg".format(pname),
-                "{0} version on conda-forge".format(pname),
-            )
-        images["{0}-platform".format(pname)] = (
-            "https://img.shields.io/conda/pn/conda-forge/{0}.svg".format(pname),
-            "{0} version on conda-forge".format(pname),
-        )
-    tab = Table(rows=rows, names=('Package name', 'Version', 'Platforms'))
+    tab = Table(rows=rows, names=('Name', 'Version', 'Build', 'Channel'))
     tab.write(file, format='ascii.rst')
-    for img, (url, alt) in images.items():
-        print("", file=file)
-        print(".. |{0}| image:: {1}".format(img, url), file=file)
-        print("   :alt: {0}".format(alt), file=file)
-        print("   :class: badge", file=file)