Repository: bids-standard/pybids

Issue:
Keeping the docs current
We're currently manually pushing the docs to https://bids-standard.github.io/pybids/, which is easy to forget, and the docs are currently out-of-date (0.9). It would be good to make an explicit process to update them or set up something automatic like ReadTheDocs.

ReadTheDocs also has the advantage of keeping old versions around, which might be useful for reference as the API changes.


Discussion:
Should be easy enough; to push the docs I just checkout the `gh-pages` branch and run `install_docs.sh`. So I think if you just add that to CI, we should be good.
I assume only on tag builds?
@tyarkoni Just FYI the docs don't build with modern Sphinx. We should add a `doc` extra (and/or `doc-requirements.txt`) with the required versions so that script can create a venv and build.
Will take a look... might be better to fix whatever's failing so we're not stuck with old sphinx versions.
> might be better to fix whatever's failing so we're not stuck with old sphinx versions

I think the `m2r` package is the main culprit (see: https://github.com/scikit-hep/pyhf/issues/818). It breaks when it's being used as a sphinx extension (like in our case).

A fix could be to call `m2r` in the docs build process, rather than using it as a sphinx extension. Should be simple enough because as it seems to me, only `CHANGELOG.md` needs to be converted.

Resolving patch:
diff --git a/doc/conf.py b/doc/conf.py
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -12,20 +12,21 @@
 #
 import os
 import sys
+from datetime import date
+
 import sphinx_rtd_theme
 
+import bids
+
 sys.path.insert(0, os.path.abspath('../'))
 
 # -- Project information -----------------------------------------------------
 
 project = 'PyBIDS'
-copyright = '2020, Developers of PyBIDS'
+copyright = '2015-{}, Developers of PyBIDS'.format(date.today().year)
 author = 'Developers of PyBIDS'
 
 currentdir = os.path.abspath(os.path.dirname(__file__))
-from bids._version import get_versions
-__version__ = get_versions()['version']
-source_version = __version__
 currentdir = os.path.abspath(os.path.dirname(__file__))
 
 # -- General configuration ---------------------------------------------------
@@ -44,20 +45,21 @@
     'sphinx.ext.githubpages',
     'sphinx.ext.napoleon',
     'numpydoc',
-    'm2r'
 ]
 
 intersphinx_mapping = {
-    'http://docs.python.org/3.5': None,
-    'http://docs.scipy.org/doc/numpy': None,
-    'http://docs.scipy.org/doc/scipy/reference': None,
-    'http://matplotlib.org/': None,
-    'http://scikit-learn.org/0.17': None,
-    'http://nipy.org/nibabel/': None,
-    'http://pandas.pydata.org/pandas-docs/stable/': None,
-    'http://neurosynth.readthedocs.io/en/latest/': None,
+    'https://docs.python.org/3.5': None,
+    'https://docs.scipy.org/doc/numpy': None,
+    'https://docs.scipy.org/doc/scipy/reference': None,
+    'https://matplotlib.org/': None,
+    'https://scikit-learn.org/0.17': None,
+    'https://nipy.org/nibabel/': None,
+    'https://pandas.pydata.org/pandas-docs/stable/': None,
+    'https://neurosynth.readthedocs.io/en/latest/': None,
 }
 
+intersphinx_timeout = 5
+
 # If your documentation needs a minimal Sphinx version, state it here.
 needs_sphinx = '2.2.0'
 
@@ -81,10 +83,9 @@
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 # The short X.Y version.
-version = ''
+version = bids.__version__
 # The full version, including alpha/beta/rc tags.
-import bids
-release = bids.__version__
+release = version
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'


Test patch: