Context The current Hub Service Guide is clearly in need of some l

Upgrade Hub Service Guide to Jupyter Book about docs HOT 3 OPEN

jnywong commented on July 26, 2024 1

Upgrade Hub Service Guide to Jupyter Book

from docs.

Comments (3)

choldgraf commented on July 26, 2024 2

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.

from docs.

jmunroe commented on July 26, 2024 1

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.

from docs.

jnywong commented on July 26, 2024

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).

from docs.

Upgrade Hub Service Guide to Jupyter Book about docs HOT 3 OPEN

Comments (3)

Related Issues (20)

Recommend Projects

React

Vue.js

Typescript

TensorFlow

Django

Laravel

D3

Recommend Topics

javascript

web

server

Machine learning

Visualization

Game

Recommend Org

Facebook

Microsoft

Google

Alibaba

D3

Tencent

	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}")