Upgrade Hub Service Guide to Jupyter Book

jnywong commented 7 months ago

Context

The current Hub Service Guide is clearly in need of some love (look at all those GH Action failures 🥲 ) and as Technical Content Developer I would like to take on more ownership of ensuring this repo is smoothly maintained!

Proposal

I propose to revamp docs.2i2c.org and upgrade it to Jupyter Book.

Why Jupyter Book?

Partnerships advocates using Jupyter Book to hub admins as the recommended tool for building out documentation for their respective communities. This is the current recommendation for building documentation in the Community Showcase Hub, since Jupyter Book allows authors to preview content "locally" on the hub before publishing content publicly (see https://github.com/2i2c-org/community-showcase/issues/44). Long-term we would like to migrate to the MyST ecosystem when the stack is more mature and hopefully upgrading to Jupyter Book now will help to ease that transition when the time comes.

Another motivating factor is that the Community Showcase Handbook would demonstrate the authoring workflow a hub admin might need in order to adopt and incorporate 2i2c maintained Hub Service Guide docs into contextualised documentation for their own communities[^1]. To that end, having a SSOT Hub Service Guide written in Jupyter Book upstream would beneficially facilitate a hub community's contextualised Jupyter Book downstream .

[^1]: e.g. the LEAP community might want to incorporate a page on gh-scoped-creds into their own docs. How that is exactly achieved in a scalable and maintainable way is a WIP for the Community Showcase Hub and I invite any suggestions or thoughts on this!

Questions ❓

Are there any reasons why the current readthedocs implementation would be preferable over Jupyter Books?
Do you forsee any limitations with maintaining and contributing to the Service Guide as a Jupyter Book?
Should we also apply the same JB recommendation to the Infrastructure Guide?

Updates and actions

### Tasks
- [ ] https://github.com/2i2c-org/docs/issues/207
- [ ] Backport new content from the Community Showcase Handbook to the Hub Service Guide, e.g. [content authoring](https://2i2c.org/community-showcase/community/content/authoring.html), [`gh-scoped-creds`](https://2i2c.org/community-showcase/user/topics/data/git.html)
- [ ] Figure out how hub admins can downstream content for contextualisation in a scalable and maintainable way and demonstrate how to do this on the Community Showcase Hub

choldgraf commented 7 months ago

A few quick thoughts:

In general I think this is a good idea. Our current documentation setup does a lot of Sphinx customization that is cool but probably too close to "power user" type infrastructure. It makes the infrastructure less maintainable in general, and distances our workflows from the workflows we're recommending from others. So I think it's a good goal to shoot for.

Jupyter Book uses Sphinx under the hood. It is basically just a distribution of Sphinx with some configuration and extensions chosen for the user. So anything in principle should be possible with JB that is possible with Sphinx.

The biggest departure between the two is how the configuration file is defined. In Sphinx it is conf.py, and in Jupyter Book it is a config.yaml file. This means that many Sphinx sites (ours included) run custom Python as a part of their Sphinx builds, but this is more complex in Jupyter Book (this is a double-edged sword, the custom python is nice but also boosts the complexity of the site).

To that point I think you're going to run into the most challenges in re-creating the logic in conf.py here:

https://github.com/2i2c-org/docs/blob/a4c876ceb82ee3b28c5e7689bced8dd7bbcf4489/conf.py#L81-L128

Some sticking points will be things like "downloading the CSV file that populates our feature matrix page" or "registering custom objects in Sphinx". Some of that may not be obvious in Jupyter Book, so doing this might require simplifying our content, but in my opinion that is probably fine.

jnywong commented 6 months ago

This work started before the existence of the Initiatives Board, so I've paused it for now before deciding collectively when priority is high enough to continue (or indeed scrubbed altogether).

jmunroe commented 6 months ago

I think this is more of an epic that is motivated by a larger initiative to rally around MystMD/JupyterBook as the way we share knowledge both internal to 2i2c and assist our communities.

I moving this issue from the initiatives board to the operations board. I will then propose a new initiative that capture this issue within it as an epic.

2i2c-org / docs