The Brian 2 simulator provides extensive documentation, examples, and tutorials. Examples and tutorials are provided in different formats: as websites, downloadable files, and jupyter notebooks which can also be executed on the binder infrastructure. Generating these formats is done partly manual, i.e. by running a script on the developer’s local machine, which is inconvenient and error-prone. In addition, the examples and tutorials are not well integrated with the rest of the documentation, which could be improved by replacing some of the Brian-specific scripts by the solutions provided by the Python ecosystem.
This project has the following aims:
Automatize the generating of example/tutorial content (e.g. by using GitHub Actions)
Run the examples/tutorials regularly to catch errors and incompatibilities introduced by changes in Brian
Remove some of the Brian-specific scripts and classes by migrating to established packages such as napoleon or sphinx-gallery
Improve the presentation of the examples/tutorials and their integration with the rest of the documentation (e.g. with sphinx-gallery).
Skill level: novice
Required skills: Python programming, experience with sphinx and CI infrastructure such as GitHub Actions helpful.
I’m Tharun MK, a 2nd-year AI & Data Science student. I’m really interested in applying for GSoC 2026 Project 2 (Update Brian documentation infrastructure).
I’ve been exploring the Brian 2 codebase over the last few days to figure out how the docs are currently built. To test things out and get a head start, I put together a local Proof of Concept (PoC) to migrate the examples over to ‘sphinx-gallery’.
I managed to get the HTML building locally with the raster plots rendering correctly (had to update some of the ‘plt’. syntax to make it work!). I just opened a Draft PR to show the initial setup here:
While looking through the repo history, I noticed that switching to ‘sphinx-gallery’ actually naturally solves a few older issues too:
Issue #610: The main migration from generate_examples.py.
Issue #171: Getting those clickable API links in the examples.
Issue #1754: Automating Jupyter/Colab notebook generation without needing a separate repo.
I also saw @thesamovar’s older comment about sphinx-gallery potentially clashing with the custom `briandoc’ extension. I’m currently studying the codebase so I can dedicate a specific phase of my GSoC timeline to fixing that exact compatibility roadblock.
I do have one quick architectural question for the mentors (@mstimberg) as I draft my proposal: For the new examples, do you prefer having detailed text explanations written directly inside the Python files using ‘# %%’ blocks (like I did in the PoC), or would you prefer the Python scripts to stay minimal with the text handled somewhere else?
Would love any early feedback from the community on my Draft PR approach! Thanks, and I’m looking forward to contributing more.
I have been working on the proposal and seeking for your feedback