Build a book within an existent Sphinx documentation

[HealthyPear]

Context

I am planning a Python3-based software package that allows to build books from a set of shipped notebooks and a book template.

My project has its Sphinx-based documentation and I was looking for a way to build an example book within my documentation, instead of e.g. a gallery of notebooks (because the point is in the end to use the much nicer book structure).

I looked here https://jupyterbook.org/en/stable/sphinx/index.html, but it's not really what I mean. I mean, the code for the book is already in the source code of the sphinx documentation and when I do make html I build also the book which is linked to the docs from, say, a example_book.rst file.

Apologies if this is already possible!

Proposal

No response

Tasks and updates

No response

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[HealthyPear]

For the moment I solved my use case by doing this:

• in conf.py I define and call a function that creates an example book template in the _static directory (this step might not be required by everyone, it's just that I have this as part of my package)
• in the Sphinx Makefile I added jupyter book build "$(SOURCEDIR)"/_static/book_example after @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
• in my RST docs I link to ./_static/book_example/_build/html/index.html

If you think this is sufficient, feel free to close this issue (but a reference of this in the docs might help someone else in the future).

[HealthyPear]

Coming back to this I noticed this documentation section (not sure if it was already there when I opened this issue though)

https://jupyterbook.org/en/stable/sphinx/index.html#convert-your-jupyter-book-into-a-sphinx-website

Did anybody try to build a Jupyter book as part of an existing sphinx documentation project?

I imagine that it should not be too hard to merge the two conf.py files before actually building (if that is the best solution)

[HealthyPear]

Update:

• I tried using jupyter-book config sphinx $(SOURCEDIR)/book_template/ into my sphinx Makefile prior to the call to sphinx-build
• I also programmatically add from ..conf import * in order to inherit from the main configuration
• then I let sphinx build everything
• the main sphinx index.rst has a toctree pointing to intro.md

unfortunately this results in the index page being shown, but without the notebooks (so only the top level is rendered).

For context, I am using pydata-sphinx-theme and I am asking to not execute the notebooks (but I should still see them as code cells)