[ENH,DOC,TST] use doctest and sphinx gallery to test/display examples

.dockerignore

@@ -1,8 +1,8 @@
 docker/Dockerfile
-
+.github
+.git
 *.pyc
 *.DS_Store
-*~
 benchmarks/
 build/
 dist

.github/workflows/pull_request.yml

@@ -7,13 +7,33 @@ jobs:
   build:
 
     runs-on: ubuntu-latest
-
+    defaults:
+      run:
+        shell: bash -l {0}
     steps:
     - uses: actions/checkout@v1
+    - uses: actions/cache@v2
+      with:
+        path: /usr/share/miniconda/envs/test
+        key: ${{ hashFiles('setup.py') }}-${{ hashFiles('requirements.txt') }}-${{ hashFiles('optional_requirements.txt') }}-conda
+    - uses: conda-incubator/setup-miniconda@v2
+      with:
+        auto-update-conda: true
+        python-version: 3.6
     # Grabbing custom dependencies and building as a pdf.
+    - name: Set up system dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install libavformat-dev libavfilter-dev libavdevice-dev ffmpeg libmp3lame-dev tesseract-ocr graphviz cmake libboost-python-dev libgraphviz-dev
+    - name: Install Python dependencies
+      run: |
+        python -m pip install --upgrade pip wheel
+        python -m pip install --upgrade --ignore-installed setuptools
+        python -m pip install --upgrade sphinx-rtd-theme sphinx-gallery --upgrade-strategy eager
+        python -m pip install -r requirements.txt -r optional-dependencies.txt --upgrade --upgrade-strategy eager
+        python -m pip install .[all]
     - uses: ammaraskar/sphinx-action@master
       with:
-        pre-build-command: "pip install sphinx-rtd-theme"
         docs-folder: "docs/"
     # Create an artifact of the html output.
     - uses: actions/upload-artifact@v1

.github/workflows/test-docker.yml

@@ -0,0 +1,157 @@
+
+name: Pull Request Docker Check
+
+on: [pull_request,workflow_dispatch,push]
+
+env:
+  EXEC_IMG: localhost:5000/pliers:exec
+  CACHE_IMG: localhost:5000/pliers:cache
+  DOC_IMG: localhost:5000/pliers:docs
+  REGISTRY_PATH: /tmp/registry
+  CACHE_PATH: /tmp/.buildx-cache
+
+
+jobs:
+  build_image:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+    -
+      name: Cache Docker Registry
+      uses: actions/cache@v2
+      with:
+        path: |
+          /tmp/registry
+        key: ${{ runner.os }}-buildx-${{ github.sha }}
+        restore-keys: |
+          ${{ runner.os }}-buildx-
+    - 
+      name: Start Docker registry
+      run: |
+        docker run -d -p 5000:5000 -e REGISTRY_STORAGE_DELETE_ENABLED=true -v ${REGISTRY_PATH}:/var/lib/registry --name registry registry:2
+    -
+      name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v1
+      with:
+        driver-opts: network=host
+    - 
+      name: Pull Base Image
+      run: |
+        set +e
+        docker pull localhost:5000/python:3.7-slim
+        success=$?
+        set -e
+        if [[ "$success" = "0" ]]; then
+            echo "Pulling from local registry"
+            docker tag localhost:5000/python:3.7-slim python:3.7-slim
+        else
+            echo "Pulling from Docker Hub"
+            docker pull python:3.7-slim
+            docker tag python:3.7-slim localhost:5000/python:3.7-slim
+            docker push localhost:5000/python:3.7-slim
+        fi
+        # set +e
+        # docker pull ${BUILDER_IMG} || true
+        # docker pull ${EXEC_IMG} || true
+    - 
+      name: Build and export executable
+      uses: docker/build-push-action@v2
+      with:
+        context: .
+        file: ./docker/Dockerfile
+        target: executable
+        cache-from: |
+          type=registry,ref=${{ env.CACHE_IMG }}
+        cache-to: |
+          type=registry,ref=${{ env.CACHE_IMG }},mode=max
+        push: true
+        tags: ${{ env.EXEC_IMG }}
+    - 
+      name: Stop Docker registry
+      run: |
+        docker run --rm --link registry anoxis/registry-cli -r http://registry:5000 --delete  --num 2
+        docker stop registry
+        docker run --rm -v ${REGISTRY_PATH}:/var/lib/registry registry:2 bin/registry garbage-collect \
+          /etc/docker/registry/config.yml
+    -
+      name: Upload Docker registry data for next steps
+      uses: actions/upload-artifact@v2
+      with:
+        name: docker-registry-data
+        path: /tmp/registry
+
+  docs:
+    runs-on: ubuntu-latest
+    needs: build_image
+    steps:
+    -
+      name: Checkout
+      uses: actions/checkout@v2
+    -
+      name: Download Docker registry data from build job
+      uses: actions/download-artifact@v2
+      with:
+        name: docker-registry-data
+        path: /tmp/registry
+    -
+      name: Cache Docker layers
+      uses: actions/cache@v2
+      with:
+        path: ${{ env.CACHE_PATH }}
+        key: ${{ runner.os }}-buildx-${{ github.sha }}
+        restore-keys: |
+          ${{ runner.os }}-buildx-
+    - 
+      name: Start Docker registry
+      run: |
+        docker run -d -p 5000:5000 -v ${REGISTRY_PATH}:/var/lib/registry --name registry registry:2
+    -
+      name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v1
+      with:
+        driver-opts: network=host
+    # - 
+    #   name: Import Docker images
+    #   run: |
+    #     docker pull ${BUILDER_IMG}
+    #     docker pull ${EXEC_IMG}
+    - 
+      name: display images
+      run: |
+        docker images
+    # - 
+    #   name: Setup tmate session
+    #   uses: mxschmitt/action-tmate@v3
+    #   timeout-minutes: 30
+    - 
+      name: Build and export
+      uses: docker/build-push-action@v2
+      with:
+        context: .
+        file: ./docker/Dockerfile
+        tags: ${{ env.DOC_IMG }}
+        target: docs
+        load: true
+        cache-from: |
+          type=registry,ref=${{ env.CACHE_IMG }}
+          type=local,src=${{ env.CACHE_PATH }}
+        cache-to: type=local,dest=${{ env.CACHE_PATH }}-new
+    # - 
+    #   name: Setup tmate session
+    #   uses: mxschmitt/action-tmate@v3
+    #   timeout-minutes: 30
+    -
+      name: run doc tests
+      run: docker run ${DOC_IMG}
+    - 
+      name: Stop Docker registry
+      run: docker stop registry
+    -
+      # Temp fix
+      # https://github.com/docker/build-push-action/issues/252
+      # https://github.com/moby/buildkit/issues/1896
+      name: Move cache
+      run: |
+        rm -rf /tmp/.buildx-cache
+        mv /tmp/.buildx-cache-new /tmp/.buildx-cache

docker/Dockerfile

@@ -1,7 +1,6 @@
 FROM python:3.7-slim as builder
 ARG DEBIAN_FRONTEND="noninteractive"
 WORKDIR /opt/pliers
-COPY . .
 # Install dependencies into a virtual environment so they can be easily copied into
 # the second stage.
 ENV PATH="/opt/venv/bin:$PATH"
@@ -14,38 +13,60 @@ RUN chmod a+rX -R . \
         libc6-dev \
         libgraphviz-dev \
         libmagic-dev \
+        libsndfile1 \
         make \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 # Run this in different layers for faster rebuilds when debugging. The extra layers
 # do impose a size penalty, because we build the final image in a separate stage.
 RUN python -m venv /opt/venv
 RUN python -m pip install --no-cache-dir --upgrade pip setuptools wheel
+RUN python -m pip install --no-cache-dir ipython notebook
+COPY requirements.txt .
 RUN python -m pip install --no-cache-dir --requirement requirements.txt
 # Install the non-GPU tensorflow package because it is smaller.
-RUN sed -i 's/tensorflow/tensorflow-cpu/g' optional-dependencies.txt \
+COPY optional-dependencies.txt .
+RUN sed -i 's/tensorflow>/tensorflow-cpu>/g' optional-dependencies.txt \
     && python -m pip install --no-cache-dir --requirement optional-dependencies.txt
+COPY . .
 RUN python -m pip install --no-cache-dir --editable .
-RUN python -m pip install --no-cache-dir ipython notebook
 RUN python -m spacy download en_core_web_sm
+RUN python -m pliers.support.download \
+    && python -m pliers.support.setup_yamnet
 
-FROM python:3.7-slim
-RUN useradd --create-home --shell /bin/bash pliers \
-    # Empty top level directories to facilitate use of the image in singularity
-    # on a box with kernel lacking overlay FS support
-    && mkdir -p /data /backup \
+FROM python:3.7-slim as base
+# Empty top level directories to facilitate use of the image in singularity
+# on a box with kernel lacking overlay FS support
+RUN mkdir -p /data /backup \
     && apt-get update -qq \
     && apt-get install -yq --no-install-recommends \
         ffmpeg \
         graphviz \
         libmagic1 \
         tesseract-ocr \
+        make \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
+
+FROM base as executable
+RUN useradd --create-home --shell /bin/bash pliers
 COPY --from=builder --chown=pliers /opt/venv /opt/venv
 COPY --from=builder --chown=pliers /opt/pliers /opt/pliers
+COPY --from=builder --chown=pliers /root/nltk_data /home/pliers/nltk_data
+COPY --from=builder --chown=pliers /root/pliers_data /home/pliers/pliers_data
 ENV PATH="/opt/venv/bin:$PATH"
 USER pliers
-RUN python -m pliers.support.download \
-    && python -m pliers.support.setup_yamnet
 WORKDIR /work
+
+FROM executable as docs
+WORKDIR /opt/pliers/docs
+RUN python -m pip install /opt/pliers['docs']
+CMD make doctest && make html
+
+FROM executable as tests
+WORKDIR /opt/pliers
+RUN python -m pip install /opt/pliers['tests']
+
+CMD py.test pliers/tests -n auto --cov=pliers --cov-report xml -m "not requires_payment" -W ignore::UserWarning &&\
+    skip_high_memory=false &&\
+    py.test pliers/tests/extractors/test_model_extractors.py -n auto --forked --cov-append --cov=pliers --cov-report xml -m "not requires_payment" -W ignore::UserWarning

docs/conf.py

@@ -20,27 +20,52 @@
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath('..'))
-
-
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
 # needs_sphinx = '1.0'
 
+# sphinx-doctest settings
+doctest_global_setup = '''
+import os
+import pandas as pd
+pd.set_option("display.max_columns", None)
+pd.set_option('display.max_colwidth', 0)
+pd.set_option('display.expand_frame_repr', False)
+'''
+
+#sphinx-gallery settings
+sphinx_gallery_conf = {
+     'examples_dirs': '../examples',   # path to your example scripts
+     'gallery_dirs': 'auto_examples',  # path to where to save gallery generated output
+     'expected_failing_examples': [],
+}
+
+if not os.environ.get('WIT_AI_API_KEY'):
+    sphinx_gallery_conf['expected_failing_examples'].append('../examples/plot_simple_graph.py')
+    sphinx_gallery_conf['expected_failing_examples'].append('../examples/plot_speech_sentiment_analysis.py')
+
+if not os.environ.get('CLARIFAI_API_KEY'):
+    sphinx_gallery_conf['expected_failing_examples'].append('../examples/plot_vision_apis.py')
+
+if not os.environ.get('GOOGLE_APPLICATION_CREDENTIALS'):
+    sphinx_gallery_conf['expected_failing_examples'].append('../examples/plot_quickstart.py')
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.doctest',
               'sphinx.ext.autosummary',
               'sphinx.ext.autosectionlabel',
               'sphinx.ext.intersphinx',
               'sphinx.ext.coverage',
               'sphinx.ext.mathjax',
               'sphinx.ext.viewcode',
               'sphinx.ext.githubpages',
-              'sphinx.ext.napoleon']
+              'sphinx.ext.napoleon',
+              'sphinx_gallery.gen_gallery']
 
 # Generate stubs
 autosummary_generate = True

docs/index.rst

@@ -8,6 +8,7 @@ Pliers documentation
 
    installation
    quickstart
+   auto_examples/index
    basic-concepts
    stimuli
    transformers