Fix reference doc issues

[mstimberg]

When fixing warnings about unused variables and similar issues quite a while back (commit 0344b00), I inadvertently broke a few features of the reference documentation – partly because some of the warnings were somewhat misleading (e.g. some function call return values weren't used, but the functions updated global variables). This should fix the issue dicussed in #1532.

I've built the updated documentation here, from a quick glance it seems to be working correctly: https://brian2.readthedocs.io/en/fix_doc_reference_issues/

Closes #1532

[thesamovar]

This all looks pretty reasonable to me!

[mstimberg]

With hindsight, I'm really embarrassed about having changed doc[start : len(doc) - stop] into doc[start:-stop]. Like, oh, these dummies don't know that you can simply use negative indices for that in Python. But well, this works well unless stop is 0 😬

[thesamovar]

I've shot myself in the foot with that one too. Increasingly think that notation might have been a mistake for Python. Some language allows you to write end-1 or something like that, which is maybe better.

[mstimberg]

Actually in this specific case, making -0 different from 0 would have worked, too :-P

[thesamovar]

Hah! Maths has things to say about that though. ;-)

Although I think in floating point representations -0.0 is different from +0.0.

[mstimberg]

Although I think in floating point representations -0.0 is different from +0.0.

It is indeed! and things like $\frac{1}{-\infty} = -0$ are even required by the IEEE standard, I think. A can of worms 😆