Deploying on ReadTheDocs with jupyterlite-sphinx#

Sphinx is the workhorse of documentation of not only the scientific Python documentation community, but also the broader Python ecosystem, and many languages beyond it. It is well adapted to building sites of any size, and tools like myst-nb enable make it very palletable to include executable, and even interactive, content.

JupyterLite assets can be copied to the default static directory in, e.g. docs/_static with html_static_path, or replace the entire site with html_extra_path

Preview Pull Requests#

You might also want to enable the Autobuild Documentation for Pull Requests feature of Read The Docs to automatically get a preview link when opening a new pull request:

an image showing the pull request preview on ReadTheDocs as a GitHub check

The Hard Way#

Below is a more advanced section on the underlying hooks and configuration to build with Sphinx.

The Sphinx deployment approach will work almost transparently with ReadTheDocs, for the small price of a .readthedocs.yml file in the root of your repository.


See the JupyterLite .readthedocs.yml for an example.


This search path can be merged several layers deep, such that your theme assets, the “gold master” JupyterLite assets, and any customizations you wish to make are combined.

html_static_path = [
    "../my-jupyterlite"        # <- these "win"

The composite directory will end up in docs/_build/_static.


See the JupyterLite for an example approach, though it’s likely a good deal more complicated than you will need, because it needs to build itself first! This complexity is managed in


A slightly more aggressive approach is to use html_extra_path to simply dump the assets directly into the doc folder. This approach can be used to deploy a site that launches directly into your JupyterLite.

Adapting the example above:

html_extra_path = ["../upstream-jupyterlite", "../my-jupyterlite"]

Again, the last-written index.html will “win” and be shown to visitors to /, which will immediately redirect to appUrl as defined in the schema.


If using Sphinx, sphinx-autobuild provides a convenient way to manage both static content and rich interactive HTML like your JupyterLite.

sphinx-autobuild docs docs/_build

This will regenerate your docs site and automatically refresh any browsers you have open. As your JupyterLite is mostly comprised of static assets, changes will not trigger a refresh by default.

Enabling the -a flag will allow reloading when static assets change, but at the price rebuild the whole site when any file changes… this can be improved with the -j<N> flag, but is not compatible with all sphinx extensions.

sphinx-autobuild docs docs/_build -aj8