Reference terminology terms

[create-issue-branch]

closes #83

[harrytodorov]

Please use this link to see the changes, as sphinx-hoverxref makes use of the "Read the Docs" API to retrieve referenced terms.

As suggested by @pablo-de-andres, the sphinx-hoverxref extension has been used to add tooltips to the terminology terms. The extension uses the :ref: role from Sphinx to cross-reference documents (see here), thus at the places we would like to use tooltips we need to convert paragraphs into ReStructuredText (currently most of the documentation is written using Markdown). This makes the adding of tooltips quite cumbersome as there are some major differences between the two formatting languages (e.g. in how links for example are formatted; ReStructuredText is very verbose).

Therefore (as suggested by @yoavnash), tooltips are added only in the "General architecture" section. If necessary in the future, they can be added to different documents.

Note: In addition to adding tooltips to the terminology terms, this issue has been used to fix a failing "Read the Docs" build. Commits 635088b and 895c334 are dealing with this.

[pablo-de-andres]

I'm not sure how sustainable this will be in the long term, considering the overhead it takes to manually have to add a term

[harrytodorov]

I'm not sure how sustainable this will be in the long term, considering the overhead it takes to manually have to add a term

I agree with you, Pablo. I don't like it as well. It is hard to integrate when Markdown is the main formatting language. I was thinking of opening an issue on their repository asking about potential Markdown support.

My second issue with the extension is that it does not give you any options of automatically "registering" terms. Say, for example, we want to "register" the term OSP and at each occurrence of it to have a tooltip over it. Or even better, to have a tooltip over it in its first N occurrences for a given user, and then remove the tooltips, as to not annoy the user.

Appended 1:
Another alternative to the Markdown support would be inlining ReStructuredText in Markdown. @pablo-de-andres do you know whether recommonmark supports this? This would clean up the code a bit more

Appended 2:
I've added an issue on the sphinx-hoverxref GitHub repository asking about Markdown support. See here