Define guidelines for adding support for external services in Jupyter Book (e.g. launch buttons, edit buttons, etc)

[choldgraf]

Context

There are several places where users can use Jupyter Book to connect with external services for interactive computing and editing. For example:

• The "Launch buttons" connect to both Jupyter-based services like BinderHubs and JupyterHubs, as well as commercial services like Colab, Deepnote, etc.
• The "Edit this page" buttons connect with content editing services like GitHub/GitLab.
• The "comments on pages" functionality in Sphinx-based Jupyter Book included many different options

In the past, representatives from open source projects or private companies have requested to add support for their services¹. This has led to some confusion about when to say "yes", what maintenance obligation we're taking on, etc. We should define this more clearly to avoid this confusion in the future.

Suggested guidelines to follow now

• There are a subset of services that are "core" to the project. We provide ongoing maintenance to this functionality, commit to supporting them long-term, and prioritize their enhancement in general. Jupyter-based services are the two main ones that come to mind.
• For all other services, we provide no guarantees for maintenance or ongoing support, but we MAY accept pull requests to provide support for these services. Here are some considerations:
  • We consider these services "community supported" and have less attention/support in general.
  • We prioritize community-driven options over commercial options.
  • We prioritize well-established commercial solutions with large userbases over more niche solutions.
  • We prioritize solutions where others are willing to commit to ongoing maintenance of an integration.
  • We generally accept external integration PRs as-is without much review, and do not spend much (if any) time on reviewing and iterating if it doesn't work.

Longer term we should define an extension point for this

In the long term, I think we should define an extension point for these kinds of integrations, so that external parties could define MyST plugins that added support for various services, rather than requiring this to be part of the core codebase. This policy is a suggestion for an intermediary solution.

Footnotes

1. For example see this PR adding deepnote to the book theme and this PR about adding Lightning Studio ↩

[rowanc1]

I think another axis of this that we should prioritize is how to make these sorts of integration point generic, such that the documentation/code allows launch buttons to be configured (e.g. open this URL with a github link param, show this icon, say "Launch ___").

I am also coming up against this with identifiers, e.g. where to put biorxiv, zenodo, arxiv, openalex, pmc, pmid, etc. identifiers. Right now we are defaulting to top level documented changes, and that requires a frontmatter change every time. We should likely move to that being more generic and can be added by users without changes. (See #1585)