Feature: Implement hover-over referencing

[s-makin]

The problem

Now that we have a functioning glossary page, one cool feature that would be awesome to have is the Wikipedia-style functionality that pops up a definition of a term or acronym when you hover over a link to the glossary.

The task

This functionality is available through the hoverxref Sphinx extension, which needs to be installed and tested to make sure the behaviour is correct.

Suggested approach

• Install the Sphinx extension according to the hoverxref documentation linked above. This is done by specifying it in the custom_conf.py file. Note, this is sometimes trickier than it sounds!
• Test to make sure it works :D

A test definition ("ACL") was included in the initial glossary implementation, on the openldap/access-control page. As long as the pop-up appears in your local build of the documentation when you hover over the term, and the text matches the expected text defined under the definition, then it's working :)

[s-makin]

@activus-d Here's one of the follow-up issues to the initial glossary implementation. Please let me know if you still want it :)

[activus-d]

@activus-d Here's one of the follow-up issues to the initial glossary implementation. Please let me know if you still want it :)

Please go ahead and assign the issue to me.

[s-makin]

Please go ahead and assign the issue to me.

Thanks @activus-d - I've assigned it to you now, let me know if you need any more info :)

[s-makin]

@activus-d Here's one of the follow-up issues to the initial glossary implementation. Please let me know if you still want it :)

Please go ahead and assign the issue to me.

Hey @activus-d, I just wanted to check in and see how things are going with this :)

[activus-d]

@s-makin I’ve started working on this. I tested the feature using my customized Makefile configuration for the Ubuntu server documentation (since the documentation seems to compile only on Linux, and I’m using a Mac M2), and it works. Now, I need to figure out how to implement the feature in the default docs configuration. I assume I’ll need to set up the docs in a container running Ubuntu. I’ll get back to this issue as early as possible next month.

[s-makin]

@s-makin I’ve started working on this. I tested the feature using my customized Makefile configuration for the Ubuntu server documentation (since the documentation seems to compile only on Linux, and I’m using a Mac M2), and it works. Now, I need to figure out how to implement the feature in the default docs configuration. I assume I’ll need to set up the docs in a container running Ubuntu. I’ll get back to this issue as early as possible next month.

That sounds great, thanks for the info! Unfortunately I can't offer any useful advice about Mac since I've never used it, but it might be worth trying Multipass just to see if that will at least let you build the docs. Keep us posted with how you get on :)

[network-charles]

I finally installed this extension locally but when I hover over a word, its stuck at "Loading".

[activus-d]

I finally installed this extension locally but when I hover over a word, its stuck at "Loading".

@network-charles My guess is that this is how it works in a local environment. The hoverxref Sphinx extension "needs a Read the Docs backend to retrieve the content that will be inserted in the tooltip". See the docs on Backend in the sphinx-hoverxref docs.

So we may have to merge your PR into the main/production branch of the Ubuntu Server Documentation for the feature to work properly.

[activus-d]

@network-charles You may also have to set up the Read the docs backend in the conf.py file. See Using readthedocs.org as backend.

[network-charles]

Interesting, I have a readthedocs account. I’ll test it using a fresh project I have and give you feedback. Thank you!

[network-charles]

You are right, @activus-d, it works when you deploy it. Thanks!

This is a screenshot from my project.