GSoC 2026 Project 2: Initial Sphinx-Gallery Infrastructure Setup

[tharun-mk]

Hi team! I am applying for GSoC 2026 Project 2. While preparing my proposal, I wanted to test how sphinx-gallery would integrate with the current conf.py setup.

I have enabled the extension, added the required gallery header, and converted the CUBA.py script to plot_CUBA.py as a local proof of concept. The HTML builds successfully on my end with the auto-generated raster plot.

Opening this as a draft so you can see the initial infrastructure in action and I can get early feedback on the approach!

[tharun-mk]

I found Issue #610 and saw @thesamovar's note from 2017 regarding sphinx-gallery potentially clashing with the custom briandoc extension. I want to assure you that my GSoC proposal will dedicate a specific phase to mapping out and resolving that exact compatibility roadblock so we can finally close that ticket.

I also noticed that fully migrating to sphinx-gallery will naturally provide an elegant, automated solution to a few other active discussions:

It natively handles the clickable API links requested in Issue #171.

It automatically generates downloadable Jupyter Notebooks, providing a much cleaner foundation for the Google Colab integration currently being discussed in PR #1754 (without needing secondary repositories).

[mstimberg]

I have enabled the extension, added the required gallery header, and converted the CUBA.py script to plot_CUBA.py as a local proof of concept. The HTML builds successfully on my end with the auto-generated raster plot.

Hi @tharun-mk, thanks for opening this PR. Could you give more details on how you tested this locally? When I run it on my machine, it appears to create an auto_examples directory, but it does not seem to be linked from anywhere in the documentation (it also contains several examples, not only the plot_CUBA one).

[tharun-mk]

Hi @mstimberg , After running sphinx-build command, I bypassed the website navigation and manually opened build/html/auto_examples/plot_CUBA.html directly in my browser. I deliberately avoided adding auto_examples to any toctree (like in index.rst) because i just made this draft pr to ask you whelther this approach was okay or not that's why i created a separate folder to show you rendering engine works.
By default, Sphinx-Gallery parses every .py file in the target directory. My filename_pattern: '/plot' setting only told it which scripts it was allowed to execute to draw graphs, but it still generated text-only HTML pages for the rest.
As we discussed on the forum, the goal is to leave scripts like frompapers/ completely untouched , while allowing the # %% block format selectively only for examples that benefit from extensive annotation.

[mstimberg]

Hi @tharun-mk, thank you for the explanation, this makes sense. One difference between sphinx-gallery and our current approach is that sphinx-gallery will run all the simulations to create the images whenever our documentation gets updated on readthedocs, whereas our current approach has all the images in a separate directory and our build process does not run any simulations at all. Do you think this would be a problem? If yes, any suggestions for how to handle this?

It automatically generates downloadable Jupyter Notebooks, providing a much cleaner foundation for the Google Colab integration currently being discussed in PR #1754 (without needing secondary repositories).

Providing downloadable notebooks is nice, but how would this then work with Google Colab (or Binder)?

Note that these are quite general questions, and if you are planning to apply for this GSoC project, you could also put your thoughts into the application document. For the prototyping stage, I think it would be easier to have one (or several) new repositories that are completely independent of Brian instead of doing things in a PR. This would allow you to try things out and have them actually built and put online somewhere.