MAINT: Doc Versioning

[sappelhoff]

With #364 #366 and #367 I started towards having versioned docs: It's true that we probably could do without them at this point, but I think it's nice to have.

This is my plan:

1. get MRG: MAINT/0.1 --> fixes to build old docs without errors #366 merged --> doesn't have any effect really ... it's only for being able to properly build the 0.1 docs after checking out git checkout maint/0.1 and calling make build-doc

2. get MRG: first step DOC versioning #364 merged ... this contains minor fixes of the current docs and a small enhancement --> previously users could only select between DEV and STABLE docs from the main page ... with that PR they'll be able to do that from all pages.

3. Change the way we handle docs:

   • circleci should build DEV docs and deploy to gh-pages branch into a dev directory
   • upon release, the maintainer who does the release manually builds the docs, and pushes them to gh-pages into a vX.Y directory (X.Y being our release)
   • I already did this on my fork. You can see the WIP here: https://github.com/sappelhoff/mne-bids/tree/gh-pages ... this is heavily copied from how it's done at MNE-Python. Check out our old docs:
     • http://stefanappelhoff.com/mne-bids/v0.1/index.html
     • http://stefanappelhoff.com/mne-bids/v0.2/index.html
     • http://stefanappelhoff.com/mne-bids/v0.3/index.html

4. Finally, with our stable docs getting their own X.Y directory on gh-pages and dev docs being deployed their continuously, we can add the links for old versions to the version selection dropdown menu that is introduced in step 2 with MRG: first step DOC versioning #364

5. profit 😄

final note: the binder links at the end of each sphinx gallery example will always resolve to the stable docs version. --> that's because the binder feature is still "experimental" and there are not a lot of customization options. ... not true, see #370

---

What do you think? @mne-tools/mne-bids

[agramfort]

sounds good !

[jasmainak]

okay just so I understand:

• this amounts to an additional step during the release process? could this be documented or automated in the Makefile?
• the binder links will not work for the older versions?

how much future maintenance work does this entail for me? :P I'm getting lazy these days ...

[sappelhoff]

this amounts to an additional step during the release process?

yes, it's not a lot of work though, because the maintainer who releases is expected to build and inspect the docs manually anyways. The additional step is copying the doc/_build/html directory and pushing it to gh-pages

could this be documented or automated in the Makefile?

could be automated, but for now I would simply document this in the Wiki where we write down the release process

the binder links will not work for the older versions?

no ... they will always redirect to STABLE. --> aaand if there is an example in 0.X that we killed in 0.X+1 (deleted/removed) then there'll be a 404.

But that's something that could be improved in the future, when more people start using binder with sphinx gallery

how much future maintenance work does this entail for me? :P I'm getting lazy these days ...

given the (unlikely/unreasonable) assumption that I won't be around: estimated 3 minutes every 6 months :-D ... else: 0 minutes

[sappelhoff]

closed with #370 and #371