Deploy rendered reports to GH-pages for example gallery

.circleci/config.yml

@@ -196,6 +196,10 @@ jobs:
             key: data-cache-1
             paths:
               - ~/mne_data/
+
+        - persist_to_workspace:  # For report deployment to gh-pages examples gallery
+            root: ~/reports/
+            paths: "*"
 
     build_docs:
       docker:
@@ -264,7 +268,28 @@ jobs:
         - add_ssh_keys:
             fingerprints:
               - "da:49:10:cd:fd:7d:2f:62:7c:78:be:4a:e1:c4:72:6c"
-
+
+    deploy_examples:
+      docker:
+        - image: node:10
+
+      steps:
+        - checkout
+        - run:
+            name: Install and configure dependencies
+            command: |
+              npm install -g --silent gh-pages@3.0.0  # Work around https://github.com/tschaub/gh-pages/issues/354
+              git config user.email "ci-build@mne.tools"
+              git config user.name "ci-build"
+        - attach_workspace:
+            at: ~/reports/
+        - run:
+            name: Deploy example reports to examples/reports dir on gh-pages branch
+            command: gh-pages --message "[skip ci] Update example reports" --dist ~/reports --dest examples/reports
+        - add_ssh_keys:
+            fingerprints:
+              - "da:49:10:cd:fd:7d:2f:62:7c:78:be:4a:e1:c4:72:6c"
+
 workflows:
   version: 2
 
@@ -276,9 +301,13 @@ workflows:
           requires:
             # - run_tests
             - build_docs
-          filters:
-            branches:
-              only: master
+            # filters:
+            #   branches:
+            #     only: master
+      - deploy_examples:
+          requires:
+            - run_tests
+            - deploy_docs
 
   scheduled:
     jobs:
@@ -288,7 +317,11 @@ workflows:
           requires:
             # - run_tests
             - build_docs
-
+      - deploy_examples:
+          requires:
+            - run_tests
+            - build_docs
+
     triggers:
       - schedule:
           cron: "0 4 * * *"

docs/mkdocs.yml

@@ -55,6 +55,8 @@ nav:
             - BEM surface: settings/source/bem.md
             - Source space & forward solution: settings/source/forward.md
             - Inverse solution: settings/source/inverse.md
+    - Examples:
+        - ds000248: examples/ds000248.md
 
 plugins:
     - search

docs/source/examples/ds000248.md

@@ -0,0 +1,54 @@
+Dataset source: [https://openneuro.org/datasets/ds000248](https://openneuro.org/datasets/ds000248)
+
+??? example "How to download this dataset"
+    Run in your terminal:
+
+    ```shell
+    openneuro-py download \
+                 --dataset=ds000248 \
+                 --include=sub-01 \
+                 --include=sub-emptyroom \
+                 --include=derivatives/freesurfer/subjects \
+                 --exclude=derivatives/freesurfer/subjects/fsaverage/mri/aparc.a2005s+aseg.mgz \
+                 --exclude=derivatives/freesurfer/subjects/fsaverage/mri/aparc+aseg.mgz \
+                 --exclude=derivatives/freesurfer/subjects/fsaverage/mri/aparc.a2009s+aseg.mgz \
+                 --exclude=derivatives/freesurfer/subjects/fsaverage/xhemi/mri/aparc+aseg.mgz \
+                 --exclude=derivatives/freesurfer/subjects/sub-01/mri/aparc+aseg.mgz \
+                 --exclude=derivatives/freesurfer/subjects/sub-01/mri/aparc.DKTatlas+aseg.mgz \
+                 --exclude=derivatives/freesurfer/subjects/sub-01/mri/aparc.DKTatlas+aseg.mgz \
+                 --exclude=derivatives/freesurfer/subjects/sub-01/mri/aparc.a2009s+aseg.mgz
+    ```
+    Note that we have to explicitly exclude numerous files due to a problem
+    with OpenNeuro's storage.
+
+## Configuration
+
+```python
+study_name = 'ds000248'
+subjects = ['01']
+rename_events = {'Smiley': 'Emoji',
+                 'Button': 'Switch'}
+conditions = ['Auditory', 'Visual', 'Auditory/Left', 'Auditory/Right']
+contrasts = [('Visual', 'Auditory'),
+             ('Auditory/Right', 'Auditory/Left')]
+
+ch_types = ['meg']
+mf_reference_run = '01'
+find_flat_channels_meg = True
+find_noisy_channels_meg = True
+use_maxwell_filter = True
+process_er = True
+noise_cov = 'emptyroom'
+
+bem_mri_images = 'FLASH'
+recreate_bem = True
+```
+
+## Generated report
+
+<div class="example-report">
+    <iframe src="reports/ds000248/sub-01_task-audiovisual_report.html"
+            title="Example report for ds000248"
+            width="100%" height="600px">
+    </iframe>
+</div>