The JupyterHub Documentation Theme#
A lightweight theme built on the PyData Sphinx Theme, for use by the JupyterHub community.
It makes minimal changes to the
pydata-sphinx-theme in order to standardize styles and a top-bar that can be shared across all JupyterHub documentation.
Defaults this theme sets#
This theme sets a few default values to standardize the look and feel across JupyterHub documentation.
If there are other standard features/customizations that would be helpful across the JupyterHub team documentation, we can probably add it here so please open an issue to discuss.
Here is a brief summary:
Sets the primary color to a slightly-darkened “Jupyter orange”
Removes primary color from headers and makes them bold to be noticeable
Aligns the header links to the left
Logo and branding#
Adds a light/dark mode JupyterHub logo
Adds a favicon
Adds icon links for our Discourse, Team Compass, and Jupyter.org
How to use this theme#
Follow these steps:
Add this theme to the
pipinstall requirements of the repo. For now, point it to the
mainbranch like so:
# in requirements.txt git+https://github.com/jupyterhub/jupyterhub-sphinx-theme
or to install locally
$ pip install git+https://github.com/jupyterhub/jupyterhub-sphinx-theme
Configure the Sphinx docs to use the theme by editing
html_theme = "jupyterhub_sphinx_theme"
Add it to your theme’s extensions:
extensions = [ "jupyterhub_sphinx_theme" ]
Make customizations on top of these defaults#
You can make customizations on top of the defaults in this theme. See the PyData theme documentation for guidance on what is possible.
In general, this theme only sets defaults, and you can override whatever you like.
Theme build system#
This theme uses the
sphinx-theme-builder tool, which is a helper tool for automatically compiling Sphinx theme assets.
This will download a local copy of NodeJS and build the theme’s assets with the environment specified in
This theme follows the
sphinx-theme-builder filesystem layout.
Build the theme locally#
You can build the documentation for this theme to preview it.
The easiest way to build the documentation in this repository is to use the
nox automation tool, a tool for quickly building environments and running commands within them.
This ensures that your environment has all the dependencies needed to build the documentation.
To do so, follow these steps:
$ pip install nox
Build the documentation:
$ nox -s docs
This should create a local environment in a
.nox folder, build the documentation (as specified in the
noxfile.py configuration), and the output will be in
To build live documentation that updates when you update local files, run the following command:
$ nox -s docs-live
Make a release#
Follow the instructions in RELEASE.md
See the kitchen sink for some example pages.
- API documentation
- Lists & Tables
- Paragraph Level Markup
- Inline Markup
- Download Links