Versioned Jupyter Books

General
1

I’ve been using Jupyter Books to write docs for a while now. E.g. for this model: https://microplastics-cluster.github.io/fragment-mnp/. I’ve gone for hosting on GitHub Pages as this seemed like a straightforward option, but it has the downside that - as far as I can tell - it’s not possible to have versioned docs.

It looks like the only way to get versioned Jupyter Books is to use Read the Docs, which is only free if you don’t mind some low-key advertising (or pay $5/month). Does anyone have any experience using Jupyter Books with Read the Docs, or alternatively, know of any other solutions to versioned Jupyter Books? Whilst I don’t necessarily mind some low-key adverts, in an ideal world I would prefer a (free) solution without - but maybe I am asking too much there!

2

Do you mean versioning like you get on Read the Docs, where you can choose to look at the docs for v1.2 or v0.3 or latest?

I have wanted to do this for our sphinx-based TopoToolbox documentation, and my research a little while ago didn’t turn up anything that seemed like it would work without a ton of fiddling with sphinx and our CI setup.

However, I just looked around, and I discovered this sphinx extension that I hadn’t seen before: GitHub - real-yfprojects/sphinx-polyversion: Build multiple versions of your sphinx docs and merge them into one website.. It is recommended in this blog post: Sphinx Documentation: Hosting Multiple Versions for Your Project | Half-Blood Programmer. I might dive into this a little more and see if it would work for TopoToolbox.

1 Like
3

Yep, exactly that!

Thanks, I will take a look :slight_smile:

4

the technology we used in the workshop in the Lake District is based on the teachbook framework (https://teachbooks.github.io/). That will generate a seperate page for each branch in your repo. If you make sure that old releases are kept as branches, that would be a easy fix?

2 Likes
5

It could probably also be configured to build tags (i.e. releases) as well as branches. However, they would be rebuilt once the github cache is expired.

1 Like
6

Thanks both, I didn’t realise Teachbooks did this! I’ll have a look into this as an option.

7

@samharrison7 I was actually trying to figure out this exact problem just this morning! When we moved our Landlab docs from landlab.rtfd.io to landlab.csdms.io we lost the capability to switch between versions of the docs. This means that people now see the docs for the latest development version, not the latest release that would get from PyPI or conda-forge.

In my searching I came across sphinx-contrib/multiversion, which looked promising and was going to try out.

1 Like
8

sphinx-polyversion also sounds promising. In the blog you link to they say,

In the past, we evaluated several existing solutions but didn’t find any that fit our needs perfectly. Without naming them…

Ugh, I wish they would just name names! I imagine one of those solutions must have been multiversion, which I linked to.

@wkearn If you do dive into this, please keep us updated!

1 Like
9

For docs, I know that MkDocs has a plugin that supports multiple versions; Setting up versioning - Material for MkDocs

MkDocs is easier to work with than Sphinx in some ways, but Python API docs don’t look as clear with it sadly.
This is because it uses markdown as an intermediary format (python code → markdown → html docs). Sphinx uses RST which is more versatile, but also more of a hassle when writing normal docs.

2 Likes
10

We’ve started to switch from writing our documentation in reStructuredText to writing it in myst, which is really just markdown, and then using the myst_sphinx extension. The docs look the same but, in my opinion, myst is so much easier to write.

11

Same here! I’ve never got on with RST, it always felt too clunky.

I’ll have to check out MkDocs, though I do really like the Python API docs that Sphinx produces.