Implement hover tooltips in documentation

[mahdienan]

This pr implements a sphinx extension to allow hovering functionality in the documentation on ReadtheDocs. The content of the text when hovering is retrieved from the glossary file which was also updated. The extension uses a sphinx role defined in _ext/HoverXTooltip.py. To make the extension match the style of NEST, we make use of

• CSS/JS defined in bootstrap.min.css,
• bootstrap.min.js, and
• hoverxtooltip.css.

The name of the role is :hxt_ref:`TERM` . This role looks for descriptions of a term in the glossary.rst file and adds the first line of the definition as the content of the pop-up. The hovering function can be also used by explicitly defining the content of the pop-up by using :hxt:`TERM <hxt:CONTENT>` .

In the glossary file entries, the first line of the descriptions for the terms will be displayed as the content of the pop-up and then there must be an empty line to prevent the entire text of the description from being displayed in the pop-up.

As an example, the PyNEST tutorials have been implemented. An example build can be found here.

[jessica-mitchell]

Thanks @mahdienan for all your hard work on this! I have a few minor English language and mark up suggestions.
Also can you please sort the glossary alphabetically (I think it's the option :sorted: but double check that).

[jougs]

@mahdienan: could you please merge master and resolve the conflict? Thanks!

[jougs]

@mahdienan: any progress on this? Thanks!

[jougs]

Many thanks for your contribution!

I have added some inline comments and have two more general questions:

• Why are the three figures part of this PR? I'm fine if they have to be here, but would not want them in if they were added by accident.
• Shouldn't this (awesome!) new feature be applied to many more files (examples, documentation files)?

[jessica-mitchell]

* Shouldn't this (awesome!) new feature be applied to many more files (examples, documentation files)?

@jougs when we were discussing this project, we decided that we wanted this PR to focus mainly on the tool, with a few examples to showcase its usage. A subsequent PR will come to add this to other documentation.

[jougs]

@jessica-mitchell: fine by me. Looking forward to that PR :-)

Regarding the failing checks on GitHub Actions:

• I already noted the missing copyright header for doc/userdoc/_ext/HoverXTooltip.py in my comments above.
• After some investigation, it seems that we can't actually silence warnings for the failing lines in pynest/examples/clopath_synapse_spike_pairing.py due to the unwillingness of pycodestyle's developers (see # noqa ignored? PyCQA/pycodestyle#924). Please ignore for now.
• I've just removed the whitespace from the empty line in testsuite/pytests/test_regression_issue-2069.py in master. Pulling should thus fix that (and at the same time shadow the problem above in the next run of the CI...)

[jessica-mitchell]

thanks @mahdienan this works well both locally and on ReadtheDocs.
I just have a couple of minor changes I'd like to see to the glossary file. Remove the subtitle 'common abbreviations in nest' and add the option :sorted: after the glossary directive

[jougs]

@mahdienan: I still would like to see the glossary descriptions consistently in upper (my preference) or lower case. As this is only a minor point, I approve now and leave the final decision to @jessica-mitchell.

[jessica-mitchell]

I agree with @jougs and the descriptions that the first word should start with upper case letter.
@mahdienan can you do that pleae? I will approve also since it is a minor change.

thanks!

[terhorstd]

Fixed last conflict that came in due to merge of #2165 . Can be merged as soon as test pass.

[jougs]

Many thanks! Merging :-)