Merge pull request #45 from oesteban/docs/build-documentation

DOC: Build versioned docs and deploy them to gh-pages

Author: oesteban

.circleci/config.yml

@@ -1,3 +1,26 @@
+docs_deploy: &docs
+  docker:
+    - image: node:8.10.0
+  steps:
+    - 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 "ci-build"
+    - add_ssh_keys:
+        fingerprints:
+          - "29:00:83:05:e9:af:5d:0f:3b:18:7a:3f:0a:98:1a:ef"
+    - run:
+        name: Deploy docs to gh-pages branch
+        command: gh-pages --dotfiles --message "doc(update) [skip ci]" --dist docs/_build/html
+
 version: 2
 jobs:
 
@@ -437,6 +460,64 @@ jobs:
     steps:
       - run: echo Deploying!
 
+  build_docs:
+    docker:
+      - image: python:3.7.4
+    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
+          command: mkdir -p $SUBJECTS_DIR
+      - run:
+          name: Install Graphviz
+          command: apt update && apt -y install graphviz
+      - run:
+          name: Install deps
+          command: 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: Generate Versioned Docs
+          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 -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
+      - store_artifacts:
+          path: ./docs/_build/html
+
+  deploy_docs_tag:
+    <<: *docs
+
+  deploy_docs_master:
+    <<: *docs
+
 workflows:
   version: 2
   build_test_deploy:
@@ -490,6 +571,7 @@ workflows:
       - deployable:
           requires:
             - build
+            - build_docs
             - test_deploy_pypi
           filters:
             branches:
@@ -514,3 +596,31 @@ workflows:
               ignore: /.*/
             tags:
               only: /.*/
+
+      - build_docs:
+          filters:
+            branches:
+              ignore:
+                - /tests?\/.*/
+                - /THP002\/.*/
+            tags:
+              only: /.*/
+
+      - deploy_docs_master:
+          requires:
+            - build_docs
+            - test_deploy_pypi
+          filters:
+            branches:
+              only: /master/
+            tags:
+              ignore: /.*/
+
+      - deploy_docs_tag:
+          requires:
+            - deployable
+          filters:
+            branches:
+              ignore: /.*/
+            tags:
+              only: /.*/

.gitignore

@@ -64,6 +64,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/api/
 
 # PyBuilder
 target/

README.rst

@@ -1,5 +1,5 @@
 ========
-dmriprep
+dMRIPrep
 ========
 
 .. image:: https://badgen.net/badge/chat/on%20mattermost/blue
@@ -17,10 +17,8 @@ dmriprep
 .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3392201.svg
     :target: https://doi.org/10.5281/zenodo.3392201
 
-.. image:: https://readthedocs.org/projects/dmriprep/badge/?version=latest
-    :target: https://dmriprep.readthedocs.io/en/latest/?badge=latest
-    :alt: Documentation Status
-
+[`Documentation <https://nipreps.github.io/dmriprep/>`__]
+[`Support at neurostars.org <https://neurostars.org/tags/dmriprep>`__]
 
 The preprocessing of diffusion MRI (dMRI) involves numerous steps to clean and standardize
 the data before fitting a particular model.
@@ -36,20 +34,17 @@ dMRIPrep equips neuroscientists with an easy-to-use and transparent preprocessin
 workflow, which can help ensure the validity of inference and the interpretability
 of results.
 
-The workflow is based on `Nipype <https://nipype.readthedocs.io>`_ and encompases a large
+The workflow is based on `Nipype <https://nipype.readthedocs.io>`__ and encompases a large
 set of tools from well-known neuroimaging packages, including
-`FSL <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/>`_,
-`ANTs <https://stnava.github.io/ANTs/>`_,
-`FreeSurfer <https://surfer.nmr.mgh.harvard.edu/>`_,
-`AFNI <https://afni.nimh.nih.gov/>`_,
-and `Nilearn <https://nilearn.github.io/>`_.
+`FSL <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/>`__,
+`ANTs <https://stnava.github.io/ANTs/>`__,
+`FreeSurfer <https://surfer.nmr.mgh.harvard.edu/>`__,
+`AFNI <https://afni.nimh.nih.gov/>`__,
+and `Nilearn <https://nilearn.github.io/>`__.
 This pipeline was designed to provide the best software implementation for each state of
 preprocessing, and will be updated as newer and better neuroimaging software becomes
 available.
 
 dMRIPrep performs basic preprocessing steps (coregistration, normalization, unwarping,
 segmentation, skullstripping etc.) providing outputs that can be
 easily submitted to a variety of tractography algorithms.
-
-[Documentation `dmriprep.org <https://dmriprep.readthedocs.io>`_]
-[Support `neurostars.org <https://neurostars.org/tags/dmriprep>`_]

dmriprep/cli/version.py

@@ -60,11 +60,11 @@ def check_latest():
 
 def is_flagged():
     """Check whether current version is flagged."""
-    # https://raw.githubusercontent.com/poldracklab/dmriprep/master/.versions.json
+    # https://raw.githubusercontent.com/nipreps/dmriprep/master/.versions.json
     flagged = tuple()
     try:
         response = requests.get(url="""\
-https://raw.githubusercontent.com/poldracklab/dmriprep/master/.versions.json""", timeout=1.0)
+https://raw.githubusercontent.com/nipreps/dmriprep/master/.versions.json""", timeout=1.0)
     except Exception:
         response = None
 

dmriprep/interfaces/__init__.py

@@ -4,8 +4,8 @@
 from nipype.interfaces.base import OutputMultiObject, SimpleInterface
 from niworkflows.interfaces.bids import (
     DerivativesDataSink as _DDS,
-    BIDSDataGrabberOutputSpec as _BIDSDataGrabberOutputSpec,
-    BIDSDataGrabberInputSpec,
+    _BIDSDataGrabberOutputSpec,
+    _BIDSDataGrabberInputSpec,
     LOGGER as _LOGGER,
 )
 
@@ -21,7 +21,7 @@ class BIDSDataGrabberOutputSpec(_BIDSDataGrabberOutputSpec):
 
 
 class BIDSDataGrabber(SimpleInterface):
-    input_spec = BIDSDataGrabberInputSpec
+    input_spec = _BIDSDataGrabberInputSpec
     output_spec = BIDSDataGrabberOutputSpec
     _require_dwis = True