Merge pull request #692 from effigies/doc/fix_1.3.x

DOC: Fix doc builds in maint/1.3.x

Author: effigies

.circleci/config.yml

@@ -1,46 +1,22 @@
-docs_deploy: &docs
-  docker:
-    - image: node:8.10.0
-  steps:
-    - run:
-        name: Check whether this is the original repo
-        command: |
-          if [[ "$CIRCLE_PROJECT_USERNAME" != "nipreps" ]]; then
-              echo "Not in nipreps/niworkflows - skipping docs deploy."
-              circleci step halt
-          fi
-    - checkout
-    - attach_workspace:
-        at: docs/_build
-    - run:
-        name: Disable jekyll builds
-        command: touch docs/_build/html/.nojekyll
-    - run:
-        name: Install and configure dependencies
-        command: |
-          npm install -g --silent [email protected]
-          git config user.email "[email protected]"
-          git config user.name "Documentation Push"
-    - add_ssh_keys:
-        fingerprints:
-          - "c8:a8:55:7d:1e:08:92:c2:86:29:7b:b4:4b:88:24:51"
-    - run:
-        name: Deploy docs to gh-pages branch
-        command: gh-pages --dotfiles --message "doc(update) [skip ci]" --dist docs/_build/html
-
-version: 2
+version: 2.1
+orbs:
+  docker: circleci/[email protected]
+
 jobs:
   build:
     machine:
-      image: ubuntu-1604:202007-01
+      # https://discuss.circleci.com/t/linux-machine-executor-images-2021-april-q2-update/39928
+      # upgrade Docker version
+      image: ubuntu-2004:202104-01
     working_directory: /tmp/src/niworkflows
     environment:
       TZ: "/usr/share/zoneinfo/America/Los_Angeles"
       SCRATCH: "/scratch"
     steps:
       - restore_cache:
           keys:
-            - build-v1-{{ .Branch }}-{{ epoch }}
+            - build-v1-{{ .Branch }}-{{ .Revision }}
+            - build-v1--{{ .Revision }}
             - build-v1-{{ .Branch }}-
             - build-v1-master-
             - build-v1-
@@ -50,8 +26,8 @@ jobs:
       - run:
           name: Docker authentication
           command: |
-            if [[ -n $DOCKER_PASS ]]; then
-              docker login -u $DOCKER_USER -p $DOCKER_PASS
+            if [[ -n $DOCKER_PAT ]]; then
+              echo "$DOCKER_PAT" | docker login -u $DOCKER_USER --password-stdin
             fi
       - run:
           name: Set up Docker registry
@@ -76,13 +52,13 @@ jobs:
             set -e
             if [[ "$success" = "0" ]]; then
                 echo "Pulling from local registry"
-                docker tag localhost:5000/ubuntu ubuntu:xenial-20191010
+                docker tag localhost:5000/ubuntu ubuntu:focal-20210416
                 docker pull localhost:5000/niworkflows
                 docker tag localhost:5000/niworkflows niworkflows:latest
             else
                 echo "Pulling from Docker Hub"
-                docker pull ubuntu:xenial-20191010
-                docker tag ubuntu:xenial-20191010 localhost:5000/ubuntu
+                docker pull ubuntu:focal-20210416
+                docker tag ubuntu:focal-20210416 localhost:5000/ubuntu
                 docker push localhost:5000/ubuntu
             fi
 
@@ -107,7 +83,7 @@ jobs:
             docker exec -it registry /bin/registry garbage-collect --delete-untagged \
                 /etc/docker/registry/config.yml
       - save_cache:
-          key: build-v1-{{ .Branch }}-{{ epoch }}
+          key: build-v1-{{ .Branch }}-{{ .Revision }}
           paths:
             - /tmp/docker
             - /tmp/images
@@ -227,7 +203,7 @@ jobs:
 
   test_pytest:
     machine:
-      image: ubuntu-1604:202007-01
+      image: ubuntu-2004:202104-01
     working_directory: /tmp/tests
     steps:
       - attach_workspace:
@@ -237,15 +213,16 @@ jobs:
           command: python -m pip install codecov
       - restore_cache:
           keys:
-            - build-v1-{{ .Branch }}-{{ epoch }}
+            - build-v1-{{ .Branch }}-{{ .Revision }}
+            - build-v1--{{ .Revision }}
             - build-v1-{{ .Branch }}-
             - build-v1-master-
             - build-v1-
       - run:
           name: Docker authentication
           command: |
-            if [[ -n $DOCKER_PASS ]]; then
-              docker login -u $DOCKER_USER -p $DOCKER_PASS
+            if [[ -n $DOCKER_PAT ]]; then
+              echo "$DOCKER_PAT" | docker login -u $DOCKER_USER --password-stdin
             fi
       - run:
           name: Set up Docker registry
@@ -277,10 +254,9 @@ jobs:
           no_output_timeout: 2h
           command: |
             mkdir -p $PWD/artifacts $PWD/summaries
-            sudo setfacl -d -m group:ubuntu:rwx $PWD
-            sudo setfacl -m group:ubuntu:rwx $PWD
-            docker run -u $( id -u ) -it --rm=false -w /src/niworkflows \
+            docker run -u $( id -u ):$( id -g ) -it --rm -w /src/niworkflows \
               -e COVERAGE_FILE=/tmp/summaries/.pytest.coverage \
+              -e SAVE_CIRCLE_ARTIFACTS="/tmp/artifacts/" \
               -e TEST_DATA_HOME=/data -v /tmp/data:/data \
               -e FS_LICENSE=/etc/fslicense.txt \
               -v /tmp/fslicense/license.txt:/etc/fslicense.txt:ro \
@@ -302,7 +278,7 @@ jobs:
           name: Run reportlet tests
           no_output_timeout: 2h
           command: |
-            docker run -u $( id -u ) -it --rm=false -w /src/niworkflows \
+            docker run -u $( id -u ):$( id -g ) -it --rm -w /src/niworkflows \
               -e COVERAGE_FILE=/tmp/summaries/.reportlets.coverage \
               -e SAVE_CIRCLE_ARTIFACTS="/tmp/artifacts/" \
               -e TEST_DATA_HOME=/data -v /tmp/data:/data \
@@ -450,7 +426,7 @@ jobs:
 
   test_package:
     docker:
-      - image: circleci/python:3.8.5
+      - image: cimg/python:3.9
     working_directory: /tmp/src/niworkflows
     steps:
       - checkout
@@ -474,7 +450,7 @@ jobs:
 
   deploy_pypi:
     docker:
-      - image: circleci/python:3.8.5
+      - image: cimg/python:3.9
     working_directory: /tmp/src/niworkflows
     steps:
       - checkout
@@ -503,12 +479,13 @@ jobs:
 
   deploy_docker:
     machine:
-      image: ubuntu-1604:202007-01
+      image: ubuntu-2004:202104-01
     working_directory: /tmp/src/
     steps:
       - restore_cache:
           keys:
-            - build-v1-{{ .Branch }}-{{ epoch }}
+            - build-v1-{{ .Branch }}-{{ .Revision }}
+            - build-v1--{{ .Revision }}
             - build-v1-{{ .Branch }}-
             - build-v1-master-
             - build-v1-
@@ -518,8 +495,8 @@ jobs:
       - run:
           name: Docker authentication
           command: |
-            if [[ -n $DOCKER_PASS ]]; then
-              docker login -u $DOCKER_USER -p $DOCKER_PASS
+            if [[ -n $DOCKER_PAT ]]; then
+              echo "$DOCKER_PAT" | docker login -u $DOCKER_USER --password-stdin
             fi
       - run:
           name: Set up Docker registry
@@ -542,28 +519,17 @@ jobs:
           name: Deploy to Docker Hub
           no_output_timeout: 40m
           command: |
-            if [[ -n "$DOCKER_PASS" ]]; then
-              docker login -u $DOCKER_USER -p $DOCKER_PASS
-              docker push nipreps/niworkflows:latest
-              docker tag nipreps/niworkflows nipreps/niworkflows:$CIRCLE_TAG
-              docker push nipreps/niworkflows:$CIRCLE_TAG
-            fi
+            docker push nipreps/niworkflows:latest
+            docker tag nipreps/niworkflows nipreps/niworkflows:$CIRCLE_TAG
+            docker push nipreps/niworkflows:$CIRCLE_TAG
 
   build_docs:
     docker:
-      - image: circleci/python:3.8.5
+      - image: cimg/python:3.9
     environment:
       - FSLOUTPUTTYPE: NIFTI
       - SUBJECTS_DIR: /tmp/subjects
     steps:
-      - restore_cache:
-          keys:
-            - docs-v1-{{ .Branch }}-{{ .Revision }}
-            - docs-v1-{{ .Branch }}-
-            - docs-v1-master
-            - docs-v1-
-          paths:
-            - ./docs/_build/_html
       - checkout
       - run:
           name: Create subjects folder
@@ -573,59 +539,21 @@ jobs:
           command: sudo apt update && sudo apt -y install graphviz
       - run:
           name: Install deps
-          command: python -m pip install --no-cache-dir -r docs/requirements.txt
-      - run:
-          name: Build only this commit
-          command: make -C docs SPHINXOPTS="-W" BUILDDIR="_build/no_version_html" html
-      - store_artifacts:
-          path: ./docs/_build/no_version_html
-      - run:
-          name: Install niworkflows
           command: |
-            python -m pip install --no-cache-dir codecov
-            python -m pip install --no-cache-dir .[all]
+            python -m pip install --no-cache-dir -U "pip>=20.3"
+            python -m pip install --no-cache-dir -r docs/requirements.txt
+            eval "$(pyenv init -)"
       - run:
-          name: Build only this commit with coverage collection
+          name: Install Niworkflows
           command: |
-            make -C docs/ clean
-            export COVERAGE_FILE=/tmp/.coverage
-            coverage run --source=niworkflows $( which sphinx-build ) \
-                -b html -W -d docs/_build/no_version_doctrees ./docs/ docs/_build/no_version_html
-            coverage xml -o /tmp/documentation.xml
-            python -m codecov --file /tmp/documentation.xml --flags documentation -e CIRCLE_JOB
+            python -m pip install .
       - run:
-          name: Uninstall NiWorkflows
-          command: |
-            python -m pip uninstall -y niworkflows
-      - run:
-          name: Generate Versioned Docs
+          name: Build only this commit
           command: |
-            set +e
-            force_versioned="$( git log --format=oneline -n 1 $CIRCLE_SHA1 | grep -i -E '\[docs?[ _]?versions?\]' )"
-            set -e
-            if [[ "x${CIRCLE_TAG}" = "x" && "${CIRCLE_BRANCH}" != "master" && "x${force_versioned}" = "x" ]]; then
-              echo "Not a tag or master branch - skipping versioned docs."
-              circleci step halt
-            else
-              make -C docs/ clean
-              make -f ./docs/Makefile versioned CURBRANCH=${CIRCLE_TAG:-$CIRCLE_BRANCH}
-            fi
-      - save_cache:
-          key: docs-v1-{{ .Branch }}-{{ .Revision }}
-          paths:
-            - ./docs/_build/_html
-      - persist_to_workspace:
-          root: docs/_build
-          paths: html
+            BRANCH=$( echo $CIRCLE_BRANCH | sed 's+/+_+g' )
+            make -C docs SPHINXOPTS="-W" BUILDDIR="$HOME/docs" OUTDIR=${CIRCLE_TAG:-$BRANCH} html
       - store_artifacts:
-          path: ./docs/_build/html
-
-  deploy_docs_tag:
-    <<: *docs
-
-  deploy_docs_master:
-    <<: *docs
-
+          path: ~/docs
 
 workflows:
   version: 2
@@ -697,23 +625,3 @@ workflows:
                 - /ds054\/.*/
             tags:
               only: /.*/
-
-      - deploy_docs_master:
-          requires:
-            - test_pytest
-            - test_package
-            - build_docs
-          filters:
-            branches:
-              only: /master/
-            tags:
-              ignore: /.*/
-
-      - deploy_docs_tag:
-          requires:
-            - deploy_docker
-          filters:
-            branches:
-              ignore: /.*/
-            tags:
-              only: /.*/

docs/Makefile

@@ -6,7 +6,7 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
-CURBRANCH     = master
+OUTDIR        = html
 PYTHONPATH    = $(PWD)
 
 # User-friendly check for sphinx-build
@@ -53,10 +53,13 @@ clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf reference/*
 
+docs-coverage:
+	PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+
 html:
-	PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/$(OUTDIR)
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/$(OUTDIR)."
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -179,6 +182,3 @@ pseudoxml:
 	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
 	@echo
 	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
-
-versioned:
-	PYTHONPATH=$(PYTHONPATH) sphinx-versioning -vv -l ./docs/conf.py build -r $(CURBRANCH) ./docs/ docs/$(BUILDDIR)/html/

docs/_static/css/version-switch.css

@@ -0,0 +1,3 @@
+.version-tree ul {
+	list-style-type: none;
+}

docs/_static/js/version-switch.js

@@ -0,0 +1,41 @@
+$(document).ready(function() {
+    var pathname = window.location.pathname;
+    var cur_ver = $("#version-slug").text().replace(/^[\n\s]+|[\n\s]+$/g, '')
+    var major_minor = "master";
+    if ( cur_ver.lastIndexOf(" (dev)") == -1 ) {
+        major_minor = `${cur_ver.split('.')[0]}.${cur_ver.split('.')[1]}`
+    }
+    var relpath = pathname.substring(pathname.lastIndexOf(major_minor)).replace(/\/$/, '');
+    var levels = relpath.split("/").length - 1
+    if ( levels == 0 ) {
+        levels = 1
+        relpath += "/"
+    }
+    var versions_file = "../".repeat(levels) + "versions.json"
+    relpath = "../".repeat(levels) + relpath
+    relpath = relpath.replace("//", "/")
+    console.log(`relpath="${relpath}", cur_ver="${cur_ver}"`)
+
+    $.getJSON(versions_file, function (data) {
+        $("#version-slug").remove();  // Unnecessary if JSON was downloaded
+
+        $.each(data["tags"].reverse(), function( i, val ) {
+            var new_path = relpath.replace(major_minor, val)
+            var item = `<li class="toctree-l2"><a class="reference internal" href="${new_path}">${val}</a></li>`
+            if ( i == 0 ) {
+                item = `<li class="toctree-l2"><a class="reference internal" href="${new_path}">${val} (Latest Release)</a></li>`
+            }
+            $("#v-tags").append(item)
+        });
+        $.each(data["heads"].reverse(), function( i, val ) {
+            var new_path = relpath.replace(major_minor, val)
+            var item = `<li class="toctree-l2"><a class="reference internal" href="${new_path}">${val}</a></li>`
+            if ( val == "master" ) {
+                item = `<li class="toctree-l2"><a class="reference internal" href="${new_path}">${val} (Development)</a></li>`
+            }
+            $("#v-tags").append(item)
+        });
+    }).fail(function() {
+      $("#version-menu").hide();  // JSON download failed - hide dropdown
+    });
+});