Create a `jupyterhub-sphinx-theme` for all JupyterHub read-the-docs sites

[manics]

Proposed change

Create a new Python package jupyterhub-sphinx-theme that includes a set of default Sphinx themes and plugins, and some configuration that can be applied across all JupyterHub read-the-docs sites.

Alternative options

Do nothing

Who would use this feature?

Everyone editing documentation on JupyterHub RTD projects.

(Optional): Suggest a solution

This was suggested by @choldgraf as part of some exploratory work on adding opengraph tags in jupyterhub/zero-to-jupyterhub-k8s#2717 and pydata/pydata-sphinx-theme#664

if we define a jupyterhub theme we could also consider defining some extensions that are automatically installed in all of our repositories (e.g. sphinx-copybutton) or some theme styles to standardize (e.g. the primary color could be jupyter orange). Another option would be to use a single-page theme like the Sphinx Book Theme and then define a topbar in the jupyterhub theme that is shared between all projects. This is what the Dask project does as well as the 2i2c docs. I actually have a PR open in the book theme to make this easier to do, would love comments if you think it'd be helpful: executablebooks/sphinx-book-theme#559

We could start by iterating on https://github.com/jupyterhub/zero-to-jupyterhub-k8s , then when we've got a stable configuration think about making it into a package?

If jupyterhub-sphinx-theme pins all dependencies exactly we can then leave the theme unpinned in all JupyterHub projects, and manage updates in one place.

[choldgraf]

Hey all - I finally had a moment to give this a shot! I have a working "JupyterHub Sphinx Theme" at this repository:

• https://github.com/choldgraf/jupyterhub-sphinx-theme
• And live preview: https://jupyterhub-sphinx-theme.readthedocs.io/en/latest/

It makes a few choices about colors, icons, etc but is otherwise totally customizable on top of it. If we ever wanted to change something in the documentation that propagated to all jupyterhub docs at the same time, we could just change it in this theme.

What do folks think?

If people think this would be useful, I am happy to move that repo into this organization and then start activating it for a few of our repositories to see how it goes.

[manics]

How about we add this to https://github.com/jupyterhub/jupyterhub-python-repo-template ?

[consideRatio]

👍 for making the jupyterhub-sphinx-theme a jupyterhub github org project and updating our python template project to rely on it!

[consideRatio]

I've proposed that https://github.com/jupyterhub/jupyterhub-python-repo-template starts relying on this theme now in jupyterhub/jupyterhub-python-repo-template#8, where @choldgraf suggested we make a move from choldgraf/ to jupyterhub/.

I suggested we go for it now, WDYT - OK to relocate choldgraf/jupyterhub-sphinx-theme to jupyterhub org?

[choldgraf]

Theme is now in the jupyterhub/ org, please try it out

Hey all, I have made several updates and this is now ready for us to try out:

• The theme is here: https://github.com/jupyterhub/jupyterhub-sphinx-theme
• It's now here on PyPI: https://pypi.org/project/jupyterhub-sphinx-theme/0.0.1/
• It's on ReadTheDocs here: https://readthedocs.org/projects/jupyterhub-sphinx-theme/builds/
• I've added @consideRatio as an owner to each of the above accounts
• I've added an API key to PYPI_KEY as a secret in the repository, and added an action that will trigger any time a GitHub release is made for the package, to upload it to PyPI.
• I've updated the theme for the latest PyData theme pre-release candidate

Try it out

You can try it out with

pip install -U jupyterhub-sphinx-theme

Can folks try it in some of our repositories and see how it looks?

[minrk]

Testing on JupyterHub: jupyterhub/jupyterhub#4363 . Looks great so far!

[manics]

If we're going ahead with recommending this org wide how about we open a docs PR somewhere to document the use of this, and close this issue?

[choldgraf]

Indeed - I think that the action to close this is:

• Add a section to our docs that describes this theme and its use
• Cross link to https://jupyterhub-sphinx-theme.readthedocs.io/en/latest/