Create conda environment for docs (#313)

* Fix docs Signed-off-by: Karen Feng <[email protected]> * Create docs deps config step Signed-off-by: Karen Feng <[email protected]> * Install Hail from docs conda env Signed-off-by: Karen Feng <[email protected]> * We need the python env for notebook generate Signed-off-by: Karen Feng <[email protected]> * Rename cache Signed-off-by: Karen Feng <[email protected]> * Only create env if nonexistent Signed-off-by: Karen Feng <[email protected]> * Fix warnings Signed-off-by: Karen Feng <[email protected]> * Fix more warnings Signed-off-by: Karen Feng <[email protected]> * Remove warning Signed-off-by: Karen Feng <[email protected]> * Clarify the docs conda env Signed-off-by: Karen Feng <[email protected]>
projectglow · Dec 1, 2020 · 1f3fecd · 1f3fecd
1 parent 06de35d
commit 1f3fecd
Show file tree

Hide file tree

Showing 7 changed files with 60 additions and 23 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -3,19 +3,34 @@ setup_base: &setup_base
   docker:
     - image: circleci/openjdk:8
 
-install_conda_deps: &install_conda_deps
+install_conda: &install_conda
   run:
-    name: Install dependencies
+    name: Install conda
     command: |
-      export PATH=$HOME/conda/bin:$PATH
       if [ ! -d "/home/circleci/conda" ]; then
         wget https://repo.anaconda.com/miniconda/Miniconda3-py37_4.8.3-Linux-x86_64.sh
         /bin/bash Miniconda3-py37_4.8.3-Linux-x86_64.sh -b -p $HOME/conda
-        conda env create -f python/environment.yml
       else
         echo "Conda already installed"
       fi
 
+create_python_env: &create_python_env
+  run:
+    name: Create conda environment for Python dependencies
+    command: |
+      if [ ! -d "/home/circleci/conda/envs/glow" ]; then
+        export PATH=$HOME/conda/bin:$PATH
+        conda env create -f python/environment.yml
+      fi
+
+create_docs_env: &create_docs_env
+  run:
+    name: Create minimal conda environment for docs dependencies
+    command: |
+      if [ ! -d "/home/circleci/conda/envs/glow-docs" ]; then
+        export PATH=$HOME/conda/bin:$PATH
+        conda env create -f docs/source/environment.yml
+      fi
 
 install_pyspark2: &install_pyspark2
   run: # Evict PySpark 3.0.0 in favor of PySpark 2.4.5
@@ -52,17 +67,19 @@ jobs:
       - checkout
       - restore_cache:
           keys:
-            - conda-deps-v1-{{ checksum "python/environment.yml" }}
-      - *install_conda_deps
+            - conda-deps-v1-{{ checksum "python/environment.yml" }}-{{ checksum "docs/source/environment.yml" }}
+      - *install_conda
+      - *create_python_env
+      - *create_docs_env
       - save_cache:
           paths:
             - /home/circleci/conda
-          key: conda-deps-v1-{{ checksum "python/environment.yml" }}
+          key: conda-deps-v1-{{ checksum "python/environment.yml" }}-{{ checksum "docs/source/environment.yml" }}
       - run:
           name: Check docs links
           environment:
           command: |
-            export PATH=$HOME/conda/envs/glow/bin:$PATH
+            export PATH=$HOME/conda/envs/glow-docs/bin:$PATH
             cd docs
             make linkcheck
       - run:
@@ -72,8 +89,7 @@ jobs:
       - run:
           name: Generate notebook source files
           command: |
-            export PATH=$HOME/conda/bin:$PATH
-            source activate glow
+            export PATH=$HOME/conda/envs/glow/bin:$PATH
             for f in $(find docs/source/_static/notebooks -type f -name '*.html'); do
                 python docs/dev/gen-nb-src.py --html "${f}" --cli-profile docs-ci
             done
@@ -86,7 +102,8 @@ jobs:
       - restore_cache:
           keys:
             - conda-deps-v1-{{ checksum "python/environment.yml" }}
-      - *install_conda_deps
+      - *install_conda
+      - *create_python_env
       - save_cache:
           paths:
             - /home/circleci/conda
@@ -144,7 +161,8 @@ jobs:
       - restore_cache:
           keys:
             - conda-deps-v1-{{ checksum "python/environment.yml" }}
-      - *install_conda_deps
+      - *install_conda
+      - *create_python_env
       - save_cache:
           paths:
             - /home/circleci/conda
@@ -194,7 +212,8 @@ jobs:
       - restore_cache:
           keys:
             - conda-deps-v1-{{ checksum "python/environment.yml" }}
-      - *install_conda_deps
+      - *install_conda
+      - *create_python_env
       - save_cache:
           paths:
             - /home/circleci/conda

diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -18,4 +18,4 @@ python:
 
 # Optionally use a Conda environment file
 conda:
-  environment: python/environment.yml
+  environment: docs/source/environment.yml
diff --git a/docs/README.md b/docs/README.md
@@ -1,4 +1,4 @@
 The Glow documentation is published with [Read the Docs](https://readthedocs.org/).
 
-To build the docs locally, activate the dev conda environment in `python/environment.yml` and then
+To build the docs locally, activate the dev conda environment in `docs/source/environment.yml` and then
 run `make livehtml` from this directory.
diff --git a/docs/source/api-docs/hail-functions.rst b/docs/source/api-docs/hail-functions.rst
@@ -1,7 +1,7 @@
 Hail Interoperation Functions
 -----------------------------
 
-Glow includes functionality to enable interoperation with `Hail <https://hail.is/>`_.
+Glow includes functionality to enable interoperation with `Hail <https://hail.is/index.html>`_.
 
 .. automodule:: glow.hail.functions
   :members:
diff --git a/docs/source/environment.yml b/docs/source/environment.yml
@@ -0,0 +1,17 @@
+name: glow-docs
+channels:
+  - bioconda
+  - conda-forge
+dependencies:
+  - hail>=0.2.58
+  - nptyping=1.3.0
+  - numpy>=1.17.4
+  - pandas>=0.25.3
+  - pip
+  - scikit-learn=0.22.1
+  - sphinx
+  - sphinx_rtd_theme
+  - typeguard=2.9.1
+  - pip:
+      - Sphinx-Substitution-Extensions==2019.6.15.0 # Substitutions in code blocks
+      - sphinx-tabs==1.1.13 # Code tabs (Python/Scala)
diff --git a/python/glow/wgr/functions.py b/python/glow/wgr/functions.py
@@ -66,11 +66,11 @@ def get_sample_ids(data: DataFrame) -> List[str]:
     Extracts sample IDs from a variant DataFrame, such as one read from PLINK files.
 
     Requires that the sample IDs:
-        - Are in `genotype.sampleId`
-        - Are the same across all the variant rows
-        - Are a list of strings
-        - Are non-empty
-        - Are unique
+    - Are in `genotype.sampleId`
+    - Are the same across all the variant rows
+    - Are a list of strings
+    - Are non-empty
+    - Are unique
 
     Args:
         data : The variant DataFrame containing sample IDs
@@ -139,6 +139,7 @@ def reshape_for_gwas(spark: SparkSession, label_df: pd.DataFrame) -> DataFrame:
     Examples:
         .. invisible-code-block:
             import pandas as pd
+
         >>> label_df = pd.DataFrame({'label1': [1, 2], 'label2': [3, 4]}, index=['sample1', 'sample2'])
         >>> reshaped = reshape_for_gwas(spark, label_df)
         >>> reshaped.head()

diff --git a/python/setup.py b/python/setup.py
@@ -21,10 +21,10 @@
       version=version,
       packages=setuptools.find_packages(),
       install_requires=[
-          'nptyping==1.1.0',
+          'nptyping==1.3.0',
           'numpy>=1.17.4',
           'pandas>=0.25.3',
-          'typeguard==2.5.0',
+          'typeguard==2.9.1',
       ],
       author='The Glow Authors',
       description='An open-source toolkit for large-scale genomic analysis',