GSoC 2022 Project Idea 10.3: Update Brian documentation infrastructure (175 h)

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)

Planned effort: 175h

Skills: Python programming, experience with sphinx and CI infrastructure such as GitHub Actions helpful

Skill level: novice

Mentors: Marcel Stimberg @mstimberg, Dan Goodman @d.goodman

Tech keywords: Brian, Python, documentation, sphinx

Hi @mstimberg and @d.goodman, I’m Neelay Shah, a final year undergraduate student from India. I’m interested in open-source development and have previously worked on developing libraries / tools for machine learning problems: EzFlow, KD-Lib, and VFormer. I have worked on setting up CI using GitHub Actions and documentation using Sphinx while developing these libraries.

I’m interested in this project and was wondering how I could start working towards a proposal. What would be some good first steps?

Thank you.

Hi @NeelayS . Thanks for your interest in our project. It is still quite early, so I would not worry about the actual proposal too much at this point. The most helpful thing to do as a first step would be to familiarize yourself with Brian’s documentation system and the sphinx package, and to understand how everything works together to give the documentation that you see under https://brian2.readthedocs.io Then try to understand what the project aims listed above are about, why they could be useful for our project, and finally what would be needed to make them happen. Don’t hesitate to ask questions if anything is unclear.

Sounds good. I’ll let you know if I have any questions.

Hello, @mstimberg @malin, I’m Sahil Saini, a second-year undergraduate student at IIT BHU India. I am a full-stack developer, interested in open-source and also have worked on some personal projects. I have experience with Git, Github, Github Actions, and python/javascript.
I am really interested in working on this project but don’t know how to start and where to start. Also, need your guidance and help to write the proposal and to start working on this.

Hi @sahilsaini110 . Thanks for yout interest in the project. Please have a look at my earlier comment for some suggestions where to start.
I will post some more details next week.

1 Like

Thank you @mstimberg for your reply. Looking forward to learn and contribute.

We have now posted some general recommendations for GSoC applications to our website, please have a look: Recommendations for GSoC 2022 applications | The Brian spiking neural network simulator

Regarding this project more specifically, 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 (with their plots) generated? How are the jupyter notebooks turned into websites? What are the limitations of these procedures?

Hello @everyone!
I am Anwer Sayeed, I am pursuing B.tech in the stream of Computer Science and Engineering from NIT Durgapur. I am currently in my 3rd year.
I am interested in web Development using the MERN stack, I have experience in automation of Documentation, CI/CD, Github Actions, skilled in c++, have also done some hands-on in Machine learning, and also have some open-source contribution experience. I am really interested in project number 10.3 Update Brian documentation infrastructure.
Thank you INCF for coming up with such a fabulous project idea. Hoping to work with this amazing organization in GSOC’22.
My Social Media Links are:
LinkedIn:- https://www.linkedin.com/in/anwersayeed/
GitHub:- anwersayeed (Anwer Sayeed) · GitHub
Thank you!

Hi @anwersayeed. Glad to hear you are interested in the project! Let us know if you have any questions that are not answered by my earlier comments and the blog post linked above.
Marcel