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.
Specifically, this project aims to:
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)
Skills: Python programming, experience with sphinx and CI infrastructure such as GitHub Actions helpful
Hi! I’m Akshay. I’m interested in taking up this project. I have experience working with Python and have built a couple of projects with the language. As for CI/CD infrastructure, I have a little experience working with Github Actions, though this I can pick up if needed if a different tool is being used as most CI architecture is TOML/YAML which can be worked with. To start off what part of the docs or any onboarding document should I have a look at?
Hi @akshayprabhu, sorry for the late reply and thanks for your interest in the project. I’ll post a general message about how to prepare the application for this project below.
Please have a look at the general coding guidelines. My comment below has more specific pointers for what to look at (last point of the list).
Best,
Marcel
Dear students,
a few general words about the application process (the first points are general for all Brian projects, and the last is specific to this project):
when you start the application on the GSoC website, you will get a template for the general structure, so I’d recommend to wait for the official start of the application period before compiling the document.
don’t hesitate to share your draft application with me so that I can give you feedback, but please don’t wait until the very last day if you want to incorporate my feedback into the final version
in the application, the detailed timeline does not matter that much (these things are always hard to predict); the important thing is to show that you 1) understand the project and its deliverables and 2) that you have the knowledge/skills to successfully finish this project.
for the second point, point to concrete proof of your experience, e.g. if you published code anywhere (e.g. for project work as part of your studies), please include a link to it.
this year, GSoC adds a bit of flexibility to the schedule: the official guideline is that over the 10 weeks of the project, “students are expected to spend on average 18 hours a week on the program”. Please include in your application how you’d like to organize time over the project, e.g. whether you prefer to do this “part-time work” over the full 10 weeks, or rather have fewer weeks with more hours, but include time off for vacation, etc. If several options work for you, you can of course write this as well. Finally, please mention any external constraints (e.g. exams) and how they fit into the schedule.
To demonstrate that you understand Brian’s current documentation infrastructure well, please describe the generation of the general documentation, the examples, and the tutorials as part of your application document. Here, “generation” means how we go from the files present in the repository to the final html files that are presented to the user on https://brian2.readthedocs.io . Parts of this process are documented in the developer documentation, but the rest has to be derived from the configuration files and scripts. Have a look at the scripts in dev/tools/docs, the Sphinx configuration file and the brian2.sphinxext package. Of course, do not hesitate to ask specific questions about things that are unclear.
Finally, a personal remark: I am officially on paternity leave, so please don’t worry if I don’t reply right away, I might be busy with other things
when you start the application on the GSoC website, you will get a template for the general structure, so I’d recommend to wait for the official start of the application period before compiling the document.
Sure, I have started working on the draft based on the template shared here on the GSoC page.
don’t hesitate to share your draft application with me so that I can give you feedback, but please don’t wait until the very last day if you want to incorporate my feedback into the final version
How should I share the draft proposal? Should I post it here or should I mail/message you?
The recommended way is to use Google Docs and to send me a share link or invite me via the interface. In general this is not something you’d share publicly with everyone, but of course this is up to you.
