Migrate team compass to JupyterBook 2?

[Arielle-Bennett]

Now that JupyterBook 2 has been released I think we should migrate this JupyterHub team compass - it would be really helpful for me as I'd like to make the most of the cross-referencing functionality!

Happy to either pick this up at the hack day or in a collaboration cafe, mayb #834 ?

[rgaiacs]

I would love to keep the documentation of all projects owned by the jupyterhub organisation with the same software stack to reduce cognitive load of contributors, see #819 and #821.

[rgaiacs]

I believe that #826 will conflict if we replace Sphinx with JupyterBook2.

[Arielle-Bennett]

Agree that things should be consistent - from my perspective there's a lot of JB2 features, particularly those which would make it easier for us to cross-reference between documentation. This might long term reduce cognitive load overall, but we would need a plan to migrate the documents. I think we could ask for help from the JD2 team for this if we decided to go this route.

I'd love for others in the team to weigh in and share their thoughts on this as well

[rgaiacs]

Only to be sure that we are all talking about the same thing, @Arielle-Bennett could you provide more details of what you are looking in the "cross-reference between documentation" feature? Thanks!

[Arielle-Bennett]

Sure thing, the documentation on it is here: https://jupyterbook.org/stable/get-started/cross-reference/

I'm particularly interested in the embed cross-referencing feature which would enable us to reuse content from other JB2 documents but also to have a single source of truth (so something only need to be updated in one place!)

[rgaiacs]

I do like the idea of have a single source of truth but

Only MyST references support the rich features like hover-previews.

This means that we would have to port the documentation of all projects.

I think this is more suitable as a sub-task for the Community Management role described in jupyter-governance/funding-proposals#6.

[minrk]

Does mystmd-based JB2 support autogenerating API docs like Sphinx autogen-api? If not, I don't think we can use it for any of our software package docs.

I think it would be fine to use JB2 in our docs-only sites like team compass and z2jh.

I thought myst could load intersphinx references, not just other myst sites. Is that not true?

[Arielle-Bennett]

So although myst will support rich text link hovers for sphinx I think, the embed feature, where content is directly built in across projects, I think is only for other myst projects: https://mystmd.org/guide/embed

I'm not sure about API autogeneration, but I can ask the project team.

[choldgraf]

API documentation is a feature that isn't yet implemented but definitely of interest to the team, give it a 👍

• Add support for API documentation generation jupyter-book/mystmd#1259

I think there's value in building up team knowledge of both technology stacks, since there will hopefully be a gradual transition or separation of duties between Sphinx and the MyST Document Engine. But I'm obviously biased here 😅. Personally, I think a big benefit of MyST is that it is simpler and faster to use in general, and so for our repos that don't need a lot of custom python stuff, or API docs, it might be worth trying. The markdown syntax is quite similar between the two (it's the same language, just slightly different core functionality between Sphinx and mystmd).

[yuvipanda]

I would be +1 to migrating pure documentation repos like this one, to gain experience with it and see how it goes! I agree that autodoc may block migrating many other repos, but this one is distinct enough that it’s ok!

[minrk]

I'd be happy to try JB2 for this repo and other more book-like repos (z2jh is probably our most high-profile candidate), keeping sphinx for package docs. This repo seems like a good first stop. It's small.

For consistency of building @rgaiacs, the commands users call don't need to change, and the docs themselves are already myst, so it should mostly be an invisible tooling shift.

[consideRatio]

I understand it as a split now where one can use jupyter-book based on mystmd, decoupled from sphinx, or use myst-parser tied to the sphinx ecosystem.

With a jupyterhub org maintainer hat on, I have some pushback towards introducing another tech stacks for docs, but with a general open-source hat on, I value that it can help the sphinx-decoupled jupyter-book initiative.

Below are some things we do via the sphinx ecosystem currently, and I am curious if there are strategies to do something similar in the sphinx-decoupled jupyter-book ecosystem already:

• theme: we are often using the pydata_sphinx_theme
• inter-site references: we sometimes use intersphinx_mapping to link to other sphinx based sites
• linkchecking: we use the sphinx linkcheck builder in our CI system to ensure links stay functional
• sphinxext.opengraph extension helps external sites generate thumbnails etc for links to the site, such as when linking to z2jh.jupyter.org from the discourse.jupyter.org forum
• sphinxext.rediraffe often helps us avoid breaking links
• sphinx_copybutton sometimes helps us provide a copy-button for code examples
• sphinx_design sometimes helps us provide tabs that can be useful when you can document smaller things in different ways (some separate instruction for linux, windows, mac perhaps)
• sphinx conf.py is used to do various repo specific things, such as generate API reference docs before documentation build