Deploying on ReadTheDocs with
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.
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.
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 = [ "_static", "../upstream-jupyterlite", "../my-jupyterlite" # <- these "win" ]
The composite directory will end up in
A slightly more aggressive approach is to use
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
will immediately redirect to
appUrl as defined in the schema.
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.
-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