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 conf.py, 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:

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.

Hint

See the JupyterLite .readthedocs.yml for an example.

html_static_path

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 = [
    "_static",
    "../upstream-jupyterlite",
    "../my-jupyterlite"        # <- these "win"
]

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

Hint

See the JupyterLite conf.py 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 dodo.py.

html_extra_path

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.

sphinx-autobuild

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