Issue: Tutorial Part 1 documentation for StateMonitor

[HarshKhilawala]

Issue with Tutorial Part 1, Link

For the above example, record=True parameter is passed to StateMonitor.

But according to documentation of StateMonitor class here ,

record parameter is used to specify the index of a particular Neuron (in case of population of Neuron)

[mstimberg]

Hi @HarshKhilawala. Thanks for opening the issue! The tutorial is correct, but the class documentation of StateMonitor is missing the information that the record argument can either be one (or many) indices, or True to designate "all neurons". The user documentation describes this correctly, though.

[HarshKhilawala]

Yes. This makes sense to me. Nevertheless I found Brian tutorials very easy to follow for newbies. That's amazing for anyone to contribute to Brian!

[mstimberg]

Actually, I just realized that we have this information in the source code (see https://github.com/brian-team/brian2/blob/master/brian2/monitors/statemonitor.py#L105-L108), but for some reason this information doesn't show up on our documentation page. I'll look into this!

[thesamovar]

Actually a bunch of stuff isn't showing up there, examples, notes, etc. Is it like that on all our docs?

[mstimberg]

Yes, I only noticed this now – one other important thing that is completely missing is the "Tutorials and examples using this" feature 😟
The problem must have been introduced somewhere 1–2 years ago. The documentation for version 2.5.1 still has all the info (e.g. for StateMonitor: https://brian2.readthedocs.io/en/2.5.1/reference/brian2.monitors.statemonitor.StateMonitor.html#statemonitor-class), while all versions ≥ 2.5.3 are lacking it…

[HarshKhilawala]

Would you like me to create PR to fix it? I would be happy to do so.

[thesamovar]

Time to crack out git bisect? :-)

[HarshKhilawala]

@thesamovar Nice to know you as part of Brian Simulator! What is git bisect?

[mstimberg]

"git bisect" is a great tool to find when a bug was introduced (or fixed), see e.g. https://www.git-tower.com/learn/git/faq/git-bisect/

In this case, it seems 0344b00 broke everything, but I am having a hard time seeing what exactly went wrong. One thing this commit did, was to delete the line that actually created the reference documentation. This has been fixed in #1474. But apparently, it did more, since adding the missing line gives you the reference back, but only in the impoverished version we are seeing now.