search

brian-team / brian2

Brian is a free, open source simulator for spiking neural networks.
http://briansimulator.org
Other
932 stars 220 forks source link

Automatically link key concepts in the documentation #489

Open thesamovar opened 9 years ago

thesamovar commented 9 years ago

It would be nice if certain key phrases like "abstract code", whenever they are used in the documentation, automatically generate a link to a page that explains them. This should be automatic because we'll never remember to do this by hand. Would this be a very difficult extension to add to sphinx? We would have some syntax that should be inserted at the place in the documentation where it is explained, and then it would handle automatically searching the whole documentation for the phrase (and there should also be a way to specify equivalent phrases that link to the same place).

mstimberg commented 9 years ago

There's built-in support in sphinx for glossaries, but it requires manually linking with something like :term:abstract code``. In our briandoc extension, we pre-process docstrings so in principle this is easy to add (https://github.com/brian-team/brian2/blob/master/brian2/sphinxext/briandoc.py#L133), but it might be a bit ugly to get the information about all the terms at that point.

thesamovar commented 9 years ago

We could do it by hand, but it feels like we'll never keep up with all the occurrences like that.

mstimberg commented 9 years ago

On the other hand, doing it manually also means we have full control, e.g. in a text that mentions a several times, I wouldn't link it every time.

thesamovar commented 9 years ago

Could just link the first time in a given page / section / paragraph?

I don't think it's too high a priority btw.

mstimberg commented 9 years ago

All is possible, but I agree that it's not a very high priority for now. In particular we should probably first look into switching to napoleon (#269) which might significantly change our briandoc extension.