-
Notifications
You must be signed in to change notification settings - Fork 92
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
MRG: first step DOC versioning #364
Conversation
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 Report
@@ Coverage Diff @@
## master #364 +/- ##
=======================================
Coverage 95.16% 95.16%
=======================================
Files 11 11
Lines 1364 1364
=======================================
Hits 1298 1298
Misses 66 66
Continue to review full report at Codecov.
|
@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 |
Travis error on macos is very uninformative : |
macosx travis is in pain in mne-python too
… |
cool ! let me know when to merge |
ready now! :-) |
Thanks @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.htmlsphinx_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:
whats_new.rst is updatedPR description includes phrase "closes <#issue-number>"