Embed HTML subproject into existing Sphinx documentation

[HealthyPear]

I am working on a project which has its own sphinx documentation (based on the pydata-sphinx-theme) and part of this project supports Jupyter Book to show off a set of notebooks.

I would like to show the jupyter book as part of my Sphinx documentation.

There are different ways I explored on how to do this, but non seem to work well.

What I end up is my HTML docs and a subfolder with separate HTML docs from the book.

Is it possible to add the index page of the book subproject as a page of my main sphinx documentation?

[yoaoxd]

If you want the notebooks to share the main site's sidebar, theme and search, I'd bring their sources into the main Sphinx build instead of embedding the generated book HTML. MyST-NB can read .ipynb files directly.

For example, install myst-nb in the docs environment, add "myst_nb" to your existing extensions list, and place a notebook at docs/notebooks/example.ipynb. Then add it to your main index.rst:

.. toctree::
   :maxdepth: 2

   notebooks/example

For an initial integration using saved notebook outputs, you can set nb_execution_mode = "off" in conf.py. Once that works, configure execution and dependencies as needed. Book-specific configuration still needs to be translated into the parent Sphinx configuration; copying _config.yml alone won't do that.

If keeping two independent builds is a requirement, publish the whole book output under a subdirectory and link to its index instead. That preserves its assets, but it remains a separate site with its own navigation/search. Including just the generated index.html won't integrate the rest of the book into Sphinx's document tree.