GSoC 2023 Project Idea 22.1 Update Brian documentation infrastructure (175h)

Description:
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.

Aims/objectives:

  • 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.

Time commitment: Short (175 h)

Lead mentor: Marcel Stimberg (@mstimberg on neurostars), Dan Goodman (@d.goodman on neurostars)

Hello @mstimberg,
I am Chandraprakash, react and JS developer who working for the last 1 year. can you share some starter resources to know more about it.

Hi @Chandraprakash-Darji. The general resources I mentioned for the other project are obviously the same here. Regarding this specific project, the most important thing to look at would be to see how our documentation is built (see e.g. the notes at the beginning here: Documentation — Brian 2 2.5.1 documentation). The documentation is built using sphinx and automatically updated/hosted via readthedocs.org. The examples and tutorials are provided as jupyter notebooks. Let us know if anything is unclear!

Hi @mstimberg,
Thank you for providing me with the resources for this project. I will definitely take a look at the documentation you mentioned and familiarize myself with the use of Sphinx and Jupyter notebooks. If I have any questions or issues, I’ll reach out to you for guidance.

Thanks again for your help and support.

Dear Mentor @mstimberg

My name is Harshwardhan Fartale, and I am a third-year student studying Electrical Engineering at the National Institute of Technology, Hamirpur. I have a keen interest in Deep Learning and Data Science, with a special emphasis on their applications in the field of Computational Neuroscience. This year, I would love to participate as a GSOC Contributor to this project.

Previously, I have contributed to the Open Source Community OpenMined as a technical writer, where I worked on documentation and blogs. Currently, I am exploring Deep Learning applications in the field of Neuroscience.

Please let me know what the next steps are for me to get started. Thank you for your time!

Best regards,
Harshwardhan Fartale

Hi @emharsha_1812, happy to hear that you are interested in the project! The first steps would be to get familiar with our current documentation infrastructure via the links in this earlier comment. Please let us know if anything is unclear.

I will also post more specific “tasks”/suggestions for regarding the application process soon.

Dear @mstimberg,

I’m Yash and I am writing to express my interest in contributing to the project. I am based in Kollam, Kerala, India doing my undergrad and I have experience in Python programming that I believe will be useful for this project.

Currently, I’m going through the starter resources that you provided and I am eager to contribute to the project. I will study the materials further and get back to you as soon as possible.

Hi @stealthflame, thanks for your interest in the project! Please don’t hesitate to ask specific (or general) questions.

@mstimberg The link for the Jupyter notebooks for the examples seems to be broken. Could you please share the valid link for the same? Thank you.

Hi @stealthflame. Could you be more specific about which link is broken?

The tutorial notebooks are here: Tutorials — Brian 2 2.5.1 documentation
Regarding the examples, I wasn’t very clear. The examples are not actually written as notebooks, the raw Python script files are here: brian2/examples at master · brian-team/brian2 · GitHub The notebook files on https://mybinder.org that are linked from the documentation are generated from the Python scripts with code available here: GitHub - brian-team/brian2-binder: Try Brian with mybinder

I thought this was the link to the tutorial notebooks, but you’ve shared the link to the notebooks in your latest comment. Thank you

Ah, apologies. Not the first link was just to meant to explain what jupyter notebooks are for those that don’t know :slight_smile:

Hello @mstimberg
First of all thank you for your reply!
I went through the complete documentation and ran the brain simulator along with the jupyter notebooks in my local machine. ( It was very fun and interesting to learn all about it btw! ) I believe I have a pretty good understanding of this project requirements along with the required technologies. Please let me know what are the furthur steps I can undertake in order to go forward.
Thanks again!

Hi everyone :wave:
I just published a general document about GsoC applications for Brian projects, please have a look!

I will be back on Monday with more details for this specific project.

Here’s some more guidance with respect to 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).

Thanks for the much more detailed guidance. Currently, I have been going through how the sphinx documentation generation works by running it through my old project’s README. I’ll start working on this and reach back to you shortly :grinning:

Hi @mstimberg
I just finished writing the proposal. How do I send it to you for review?

Hi @Achintya . Please either use the “Message” functionality (after clicking on my user name) here, or send me an email at marcel (dot) stimberg (at) inserm (dot) fr.

Hi @mstimberg , I’m an MS (by Res.) student at IIIT Hyderabad working on Computational Neuroscience. I have used Brian2 as part of an introductory course on neural modeling.

I have previously been a TA for an advanced programming course on Data Structures and Algorithms. I have also worked on research projects on Computer Vision and Natural Language Processing, using tools such as PyTorch, Keras, and TensorFlow. I’m also familiar with Bash.

I’m interested in this project. I know it’s very late but can we schedule a meeting to draft a proposal?

Dear @Kumar_Neelabh . Thanks for your interest in the project! Unfortunately, I won’t be able to schedule a meeting before the deadline of the proposal. If you can share a draft (ideally on Google Docs or something similar, sharing the link via a private message on neurostars or via email at marcel (dot) stimberg (at) inserm (dot) fr), I can still try to have a look and give you feedback.