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
I am Alex, an undergrad at the faculty of Cybernetics and Informatics in Bucharest. I am a user of brian2 and documenting my interests in SNNs in my Medium Blogs
I write here to collaborate and coordinate with other contributors to achieve a clear vision about this project. I already opened a draft PR a couple days ago related to setting up header files and migrating to sphinx Gallery. My PR
I noticed that @tharun_mk works on the same tasks and he raised some good points towards the direction. I also have some questions so i could draft my proposal, like how are automatic example and tutorial generation supposed to happen? In the INCF proposal it mentions GitHub actions but it could also be done almost entirely with the sphinx documentation framework, using the CI tools only to run the scripts.
I propose to @tharun_mk and other contributors that chose to take on this project to document, ask questions and keep up to date on this thread so we know how to be the most effective.
I am an active community member on brian discourse group. I intend to take on this project as part of GSoC
Hi Alex,
It is great to meet you! I completely agree that coordinating and discussing things here is the best way to ensure we all understand the project’s vision. Thanks for opening up the discussion!
To answer your question about the automatic generation: you are spot on with your intuition. The actual execution and generation of the .py examples and .ipynb tutorials are handled entirely by the sphinx-gallery extension natively during the standard sphinx-build process.
The GitHub Actions workflow mentioned in the INCF proposal acts purely as the Continuous Integration (CI) gatekeeper. By running sphinx-build -b html . _build/html -W inside the action, it turns warnings into fatal errors. Because sphinx-gallery executes the Python code live, this ensures that if a future pull request breaks a tutorial script, the Action fails and blocks the merge, preventing broken docs from reaching the live site.
Regarding that stale 2017 branch you found—that is a great catch. I was actually digging into that exact attempt (Issue #610) over the weekend. The main roadblock they hit back then was that sphinx-gallery clashed with Brian’s custom briandoc and docscrape extensions when parsing Python files.
In my local testing, I found that we can resolve this 2017 blocker entirely by deprecating the legacy docscrape scripts and replacing them with the modern sphinx.ext.napoleon extension. Napoleon natively handles the NumPy-style docstrings and complex math without clashing with sphinx-gallery, allowing briandoc to cleanly generate the cross-references (like the NeuronGroup parameters) without throwing extension errors.
By
Tharun M K
My name is Aman Chawhan, and I’m a prospective GSoC 2026 applicant interested in the - Update Brian documentation infrastructure project (175h). Over the past few days I’ve been trying to understand the current documentation setup and the discussions around the previous GSoC work in this area.
Preparation so far:
1- I read through the 2022 project discussions (#10.2, #10.4, #10.5) as well as the Recommendations for GSoC applicants page.
2 - I cloned the Brian2 repository and explored how examples are currently generated, particularly the use of brian2.tests and the existing scripts.
3- To get a better sense of the workflow, I created a small proof-of-concept using sphinx-gallery with a few example scripts to see how automatic example generation might integrate with the documentation.
4 - I’ve also been exploring documentation tooling in another open-source project (MLLAM / neural-lam), which has helped me become more familiar with Sphinx, Jupyter Book, and CI-based documentation builds.
My current understanding of the project:
The main goal seems to be improving and modernizing the documentation workflow by automating example generation (possibly through GitHub Actions), replacing some custom scripts with more standard tools such as “sphinx-gallery”, and improving how tutorials and examples are presented in the documentation.
A couple of questions I had while reading the previous discussions:
In the 2022 threads, there was a suggestion that applicants should try to identify “realistic errors a user could make” From your experience, what are the most common mistakes new users make when running Brian examples? I’d like to think about how documentation and examples could better guide users or surface clearer error messages.
Regarding the potential migration to sphinx-gallery, is there a preference for keeping the current .py example scripts and generating notebooks dynamically, or would converting some examples directly to .ipynb be considered acceptable?
I’m very interested in contributing to this effort and would really appreciate any feedback or suggestions on whether my current approach makes sense.
Hi team, I’m Akshay Jaiswal. I’ve been performing a ‘Developer Experience’ audit of the Brian2 docs. While setting up locally on Windows, I encountered the Python 3.12 requirement and the MSVC compiler bottleneck.
This highlighted a key opportunity for the project: Decoupling the documentation build from the core simulation engine. I’m planning to propose a ‘Doc-only’ build mode using GitHub Actions and possibly a Dockerized environment so contributors can edit tutorials without needing a full C++ build environment. Would this focus on ‘portability’ be a valuable addition to the project scope?
Hi everyone, sorry for not engaging with your questions in detail earlier, I’ll answer some in the post below. Please also note that I’ve posted some general recommendations for GSoC applications to our website: GSoC 2026 | The Brian spiking neural network simulator
Regarding this specific project: a core part of the application should be describing Brian’s current documentation system and its limitations. For example, what tools are used to build the general HTML documentation? How are the pages showing the examples and their plots generated? How are the jupyter notebooks turned into websites? What are the limitations of these procedures? What are existing packages/extensions that could be useful and how would they be integrated into our current workflow (on a rather general level, of course; figuring out the details will be part of the project). Looking into other open-source project’s setup could of course be a source of inspiration.
As promised, here a few answers to questions that came up in this thread:
I think for some of the examples this might make sense, but given the number of examples, we won’t do this for all of them. In particular, the examples of the from_papers category have quite different styles depending on what the respective authors preferred, and the idea would be not to touch the content of these scripts.
This is indeed something to think about. The most important thing is to keep things simple, both for the authors of examples and for us developers when maintaining them. I think the current approach where tutorials are notebooks and examples are Python files that are automatically converted to notebooks is probably the best one. As in @tharun_mk’s example, allowing the “# %%”-format (Notebooks as code — Jupytext documentation) is probably a good intermediate solution for examples that want to benefit from more extensive annotation.
I am not sure that I understand this fully: having a compiler isn’t a requirement to build the document (or to run Brian, actually) – C++ code generation is always optional. Improving the developer experience is always welcome, but we do already have a docker environment (briansimulator/brian - Docker Image) and a devcontainer using this environment (brian2/.devcontainer at master · brian-team/brian2 · GitHub). This setup also allows you to directly run and edit Brian2 code in the browser using GitHub’s codespace feature.
Hey @mstimberg Thanks for the feedback, Sir I’ve updated my proposal to prioritize the sphinx-gallery migration and doc-testing as you suggested. Looking forward to it!
