MRG: first step DOC versioning (#364)

* FIX minor doc formatting+linking

* typo

* ENH: Add navbar for VERSIONS to docs

* pytest-faulthandler is now part of pytest (>5.0)

doc/_templates/navbar.html

@@ -0,0 +1,16 @@
+{% extends "!navbar.html" %}
+
+{% block navbarsearch %}
+<div class="navbar-form navbar-right navbar-btn dropdown btn-group-sm" style="margin-left: 20px; margin-top: 5px; margin-bottom: 5px">
+  <button type="button" class="btn btn-{% if (build_dev_html|tobool) %}danger{% else %}primary{% endif %} navbar-btn dropdown-toggle" id="dropdownMenu1" data-toggle="dropdown">
+    v{{ release }}
+    <span class="caret"></span>
+  </button>
+  <ul class="dropdown-menu" aria-labelledby="dropdownMenu1">
+    <li><a href="https://circleci.com/api/v1.1/project/github/mne-tools/mne-bids/latest/artifacts/0/html/index.html?branch=master">Development</a></li>
+    <li><a href="https://mne.tools/mne-bids/">Stable</a></li>
+  </ul>
+</div>
+
+{{ super() }}
+{% endblock %}

doc/conf.py

@@ -9,13 +9,6 @@
 
 import mne_bids
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-curdir = os.path.dirname(__file__)
-sys.path.append(os.path.abspath(os.path.join(curdir, '..', 'mne_bids')))
-sys.path.append(os.path.abspath(os.path.join(curdir, 'sphinxext')))
-
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -88,6 +81,9 @@
 html_theme = 'bootstrap'
 html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
@@ -102,19 +98,21 @@
         ("API", "api"),
         ("CLI", "generated/cli"),
         ("What's new", "whats_new"),
-        ("Github", "https://github.com/mne-tools/mne-bids", True),
+        ("GitHub", "https://github.com/mne-tools/mne-bids", True),
     ]}
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
-    'mne': ('https://mne.tools/stable/', None),
+    'mne': ('https://mne.tools/dev', None),
     'numpy': ('https://www.numpy.org/devdocs', None),
     'scipy': ('https://scipy.github.io/devdocs', None),
     'matplotlib': ('https://matplotlib.org', None),
-    'nilearn': ('http://nilearn.github.io', None),
+    'nilearn': ('https://nilearn.github.io', None),
 }
+intersphinx_timeout = 5
+
 
 sphinx_gallery_conf = {
     'examples_dirs': '../examples',

doc/environment.yml

@@ -20,7 +20,6 @@ dependencies:
   - pytest<5.4
   - pytest-cov
   - pytest-sugar
-  - pytest-faulthandler
   - check-manifest
   - pydocstyle
   - sphinx

environment.yml

@@ -19,7 +19,6 @@ dependencies:
   - pytest<5.4
   - pytest-cov
   - pytest-sugar
-  - pytest-faulthandler
   - check-manifest
   - pydocstyle
   - sphinx

examples/convert_empty_room.py

@@ -1,5 +1,5 @@
 """
-.. _ex-convert-mne-sample:
+.. _ex-convert-empty-room:
 
 ======================================
 Storing empty room data in BIDS format

examples/convert_group_studies.py

@@ -8,7 +8,7 @@
 https://openneuro.org/datasets/ds000117
 
 We recommend that you go through the more basic BIDS conversion example before
-checking out this group conversion example: :ref:`_ex-convert-mne-sample`
+checking out this group conversion example: :ref:`ex-convert-mne-sample`
 
 References
 ----------

mne_bids/write.py

@@ -1382,11 +1382,14 @@ def write_anat(bids_root, subject, t1w, session=None, acquisition=None,
         If True, deface with default parameters.
         `trans` and `raw` must not be `None` if True.
         If dict, accepts the following keys:
-            `inset`: how far back in millimeters to start defacing
-                     relative to the nasion (default 20)
-            `theta`: is the angle of the defacing shear in degrees relative
-                     to the normal to the plane passing through the anatomical
-                     landmarks (default 35).
+
+        - `inset`: how far back in millimeters to start defacing
+          relative to the nasion (default 20)
+
+        - `theta`: is the angle of the defacing shear in degrees relative
+          to the normal to the plane passing through the anatomical
+          landmarks (default 35).
+
     landmarks: instance of DigMontage | str
         The DigMontage or filepath to a DigMontage with landmarks that can be
         passed to provide information for defacing. Landmarks can be determined