Download button for both .ipynb and .md

[teutoburg]

The (excellent) Sphinx book theme seems to provide the option to include both the (source) .md file and the (executed) .ipynb file in the "download button" in the header, for notebooks that use MyST-nb. An example of this can be seen e.g. in https://sphinx-book-theme.readthedocs.io/en/stable/reference/notebooks.html

I really like this feature, because it allows to only keep the .md file in the repo, while also providing the .ipynb file for users to download and "play with", without having to manually convert it with e.g. jupytext. However, even after two days of trying and googeling and looking through source code, I cannot seem to get this to work for our package's documentation. I have no issues getting the myst-based notebook to run and render in the final documentation, but the download button only shows .md and .pdf options.

I did find the (probably) relevant section in the theme here: https://github.com/executablebooks/sphinx-book-theme/blob/c47d8e46fbce78492abd8a5adfe41083bb7ba121/src/sphinx_book_theme/header_buttons/launch.py#L59C5-L75C54
But I can't figure out how to get the "paired notebook" in the _sources directory during the build on readthedocs. I thought of putting a jupytext converting command in somewhere, but sphinx-book-theme's own documentation seems to manage it without this arguably hacky solution.

Any help or guidance on this would be greatly appreciated!! I also found a discussion from another project (from May 2023) talking about the exact same issue, without any conclusion, so it would probably be a very useful addition for the theme's documentation in general.

[agoose77]

Hi @teutoburg!

Would you be willing to share a link to your repo, so I can take a closer look?

[teutoburg]

Thanks for the quick reply!
Here's the repo in question (mind the branch): https://github.com/AstarVienna/irdb/tree/fh/rtd
It is currently a huge mess, as we're in the process of completely reworking the documentation. Here's a link to one of the md-based pages I've been experimenting with: https://github.com/AstarVienna/irdb/blob/fh/rtd/METIS/docs/example_notebooks/testnotebook3.md
And finally here's the direct link to the RTD build for the same page: https://irdb.readthedocs.io/en/fh-rtd/METIS/docs/example_notebooks/testnotebook3.html where the missing .ipynb download option can be seen.

Hope this is useful.

[billbrod]

I think I'm having a similar issue -- downloading the ipynb file is only given as an option if I also include the launch_buttons option. Given that I want to allow a download, but not the launch button, I'm not quite sure how to proceed...

(Though I would be interested in launch button if I could customize the url more, I just want {binderhub_url}?filepath={path_to_docs}/path/to/file.ipynb, without the attempt to add the github url. Currently I'm getting around this by just adding a Binder badge as an icon link)

I'm using text-based notebooks from myst-nb.

I can open a bug report if this is unexpected behavior

Versions of relevant packages:

• sphinx-book-theme 1.1.3
• pydata-sphinx-theme 0.15.4
• myst-nb 1.1.1
• myst-parser 3.0.1
• Sphinx 7.3.7
• jupytext 1.16.2

Some more details:

• When launch_buttons is not included, build/html/_sources does not include any ipynb files (just .md), but build/jupyter_execute does include the ipynb files.
• Copying the ipynb files from build/jupyter_execute to build/html/_sources after the build does not fix the problem (unsurprisingly)
• When launch_buttons is included, both locations include ipynb files.