Upgrade Hub Service Guide to Jupyter Book

[jnywong]

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 2i2c-org/community-showcase#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¹. 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 .

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

Beta Give feedback

1. [EPIC] Port existing Hub Service Guide content to Jupyter Book #207
   1 of 3
   +0
   
2. Backport new content from the Community Showcase Handbook to the Hub Service Guide, e.g. content authoring, gh-scoped-creds
3. 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

Footnotes

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! ↩

[choldgraf]

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:

docs/conf.py

Lines 81 to 128 in a4c876c

	widget_embed_code = """
	// This is the function to open the widget code
	function openWidget() {
	FreshworksWidget('open');
	}
	// FreshWorks widget loading code
	window.fwSettings={
	'widget_id':80000009162
	};
	!function(){if("function"!=typeof window.FreshworksWidget){var n=function(){n.q.push(arguments)};n.q=[],window.FreshworksWidget=n}}()
	"""
	def setup(app):
	app.add_css_file("custom.css")
	app.add_crossref_type("team", "team")
	app.add_crossref_type("role", "role")
	# Add the JS code for our FreshDesk support widget
	# ref: https://support.freshdesk.com/en/support/solutions/articles/239273-setting-up-your-help-widget
	# ref: https://support.freshdesk.com/en/support/solutions/articles/50000001015-launching-the-widget-when-a-button-is-clicked
	app.add_js_file(None, body=widget_embed_code)
	app.add_js_file("https://euc-widget.freshworks.com/widgets/80000009162.js", **{"async": "", "defer": ""})
	# -- Custom scripts -------------------------------------------------
	# Generate the feature table
	import subprocess
	from pathlib import Path
	build_assets = Path("build_assets")
	build_assets.mkdir(exist_ok=True)
	subprocess.run(["python", "feature-table.py"], cwd="scripts")
	# Download figures we keep in Google Drive
	from requests import get
	figures = {
	"https://drive.google.com/uc?export=download&id=1Mr51-s3D_KHPsAuTXbczaQ7mlPZUs9gm": "collaborative_learning_hub.png",
	"https://drive.google.com/uc?export=download&id=16r5xE7SguunLfMh5LhSynSUfjb7IXs_n": "shared_responsibility_diagram.png",
	"https://drive.google.com/uc?export=download&id=1gWAIQVKcB-uxuJsBHqlDlRTq88oki1zn": "scalable_research_hub.png",
	}
	for url, filename in figures.items():
	path_image = Path(__file__).parent / "images" / filename
	if not path_image.exists():
	print(f"Downloading {filename}...")
	resp = get(url)
	path_image.write_bytes(resp.content)
	else:
	print(f"Diagram image exists, delete this file to re-download: {path_image}")

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]

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]

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.