jupyter-book
jupyter-book copied to clipboard
executablebooks
Versioning support
Is your feature request related to a problem? Please describe. It would be nice to have support for building versions of a book so that books used for courses, for example, could be versioned by year, semester, etc.
Describe the solution you'd like There are already a few Sphinx-friendly solutions for versioning. Perhaps the most easily adapted would be sphinx-multiversion, as it appears to work with recent versions of Sphinx and do minimal modification of the internal Sphinx stuff.
Describe alternatives you've considered I haven't really tested any alternatives for this issue. I lack the knowledge of the guts of Sphinx to know how to integrate sphinx-multiversion directly, and it seems that building on Read the Docs may not be that straightforward (but version support would be provided).
Additional context This was mentioned back in #31 , but that was closed pending the migration to using Sphinx as the back-end for Jupyter-Book. Perhaps this issue can be considered again?
I think it's a good idea 👍 the main question is implementation - e.g., if we can get Jupyter Book building on ReadTheDocs, then we should be able to use their branch-based versioning as well.
I agree, and don't really have a strong opinion on which option would be considered. I suppose the sphinx-multiversion option is nice in the sense that documentation could be hosted anywhere. A colleague and I can probably tinker a bit with ReadTheDocs. I'll post here if we do anything useful.
Please let us know how it goes! This would be a useful feature for many classes, I suspect
OK, so it turns out neither of us really have time to dive into getting jupyter-book running on ReadTheDocs, so we're opting to use the sphinx-book-theme with Sphinx to have the jupyter-book appearance with versioning provide by ReadTheDocs. It would be great to eventually be able to build everything with jupyter-book and deploy on ReadTheDocs, but I can't devote much time to this at the moment.
I agree this would be important for distribution of a stable URL to a class, say. I lack the expertise to pull off a general solution. My kludge was to create an organization for the book and manually create a v1.0 repo to host the html.
I'd love to see this accomplished by adding readthedocs support (cc @ericholscher). Otherwise - you probably could accomplish the same thing by building the book and placing the outputs in a folder corresponding to a particular version.
I accidentally duplicated this issue, sorry. I think I will try to do more or less what @choldgraf suggests, which is I think what is happening in metawards.
and it seems that building on Read the Docs may not be that straightforward
FYI, Jupyter Book is now compatible with Read the Docs, see https://jupyterbook.org/publish/readthedocs.html!
It would be great with some kind of versioning support in jupyter-book proper, i.e., that doesn't depend on Read the Docs. Something like the msmb_theme would be nice, which basically reads version information from a json file and populates the sidebar.
I'd also be very keen on having a dropmenu to select different versions (stable, dev) à la RtD.
In https://github.com/executablebooks/jupyter-book/issues/1037 there is a mention of the needed groundwork in https://github.com/pydata/pydata-sphinx-theme/issues/23 which as far as i understand has been done and merged. I was wondering if there is any developments regarding a straightforward way of adding multiple versions support?
Once we release the next version of Jupyter Book, we'll have versioning via ReadTheDocs. For example, see the version dropdown in the bottom left on latest/: https://jupyterbook.org/en/latest/publish/readthedocs.html
We can also look into the same version dropdown support that's in PyData, though I think the question is where this would live in the book UI without cluttering it too much. Maybe that is work that we could put into a header:
- https://github.com/executablebooks/sphinx-book-theme/pull/559
I'm curious if anyone has implemented this. I have a nice setup using Jupyter Book for internal docs at my company, but it would be great if we could have RTD-like version selectors. sphinx-multiversion seems to do more or less what I want but I have no idea how that might play with JB.
I'm curious if anyone has implemented this...
Here's an example. Note, the main branch hasn't been updated yet so it's a WIP. However, the develop branch is live.
- https://buildingmotif.readthedocs.io/en/latest/README.html
