MRG: first step DOC versioning

[sappelhoff]

I started this PR with high hopes of bringing versioned docs to MNE-BIDS (currently we only have one stable version ... and the "latest" version as hosted in CircleCI artifacts)

... buuut after too many hours of hacking, there are no news apart from these small fixes I now present in this PR 🤷‍♂️

Anyhow, this is what I tried and why it didn't work:

• sphinxcontrib-versioning is what I started with. It's being used in https://poldracklab.github.io/smriprep/ ... as was recommended by one of our JOSS reviewers in December 2019. --> unfortunately, that repo's maintainer is very busy and the code is not being kept well up to date ... see Incompatible with Sphinx >= 2.0 sphinx-contrib/sphinxcontrib-versioning#77 and sphinx1.7+: ImportError workaround, allows to see help sphinx-contrib/sphinxcontrib-versioning#78 ... I didn't try to force this package to work and instead moved on to the alternative below:

• sphinx_multiversion ... which seems pretty nice once correctly configured. See this page as an example (click on versions tab in lower left of page): https://mixxx.org/manual/2.3/en/index.html

  • issues: the build seems to copy each branch/tag (can be configured which ones precisely) into temporary directories to build one version per branch/tag ... and then there were clashes with Sphinx Gallery that suddenly didn't find it's README.txt anymore. --> This may be resolvable. But given that sphinx_multiversion itself seems brand new, it probably means lots of hack work. (edit, helpful link to get sidebars activated in bootstrap here)

Summary: Neither of the two packages seem very robust ... but they could be used for our purposes ... needs more time investment though and I've had enough for an evening :)

If somebody else wants to give this a shot, please do it!

EDIT: An alternative is of course to do it like in MNE-Python and manually upload the docs for each release: https://github.com/mne-tools/mne-tools.github.io ... and then adding some html/css templates to link to those

Edit2: Another alternative would be a move to https://readthedocs.org/, but that would mean giving up our current system, relying on GitHub Pages.

Merge checklist

Maintainer, please confirm the following before merging:

• All comments resolved
• This is not your own PR
• All CIs are happy
• PR title starts with [MRG]
• whats_new.rst is updated
• PR description includes phrase "closes <#issue-number>"
• Commit history does not contain any merge commits

[jasmainak]

I think given that we are a young and light package with very few dependencies, we can ask people to update to the latest version periodically. I know that readthedocs supports versioning but I like the template that we have :)

[codecov-io]

Codecov Report

Merging #364 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #364   +/-   ##
=======================================
  Coverage   95.16%   95.16%           
=======================================
  Files          11       11           
  Lines        1364     1364           
=======================================
  Hits         1298     1298           
  Misses         66       66

Impacted Files	Coverage Δ
mne_bids/write.py	97.52% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update baff3f7...bb84e2f. Read the comment docs.

[sappelhoff]

@jasmainak I added a small navigation dropdown (copied from MNE-Python), which I think is an enhancement :-)

This is how it looks like in the rendered preview: https://1721-89170358-gh.circle-artifacts.com/0/html/index.html

[sappelhoff]

Travis error on macos is very uninformative : An error occurred while generating the build script.

[agramfort]

macosx travis is in pain in mne-python too

…

[jasmainak]

cool ! let me know when to merge

[sappelhoff]

cool ! let me know when to merge

ready now! :-)

[jasmainak]

Thanks @sappelhoff !