Development

This is a very small guide to help with the development of this extension. Since it needs a backend and the event is only triggered only on mouse hover, it could be tedious if you don’t know these tips & tricks.

Backend

This extension needs a Read the Docs backend to retrieve the content that will be inserted in the tooltip. You can use the API from https://readthedocs.org directly or a local instance of Read the Docs as backend.

Using readthedocs.org as backend

This is the easiest way to have the backend working, since you do not need to do anything. Although, you need to use an already existent project in Read the Docs.

To setup this approach, you need to put these settings in the conf.py of your docs:

hoverxref_project = 'sphinx-hoverxref'
hoverxref_version = 'latest'
hoverxref_api_host = 'https://readthedocs.org'

After building the documentation all the requests will be done to URLs like:

https://readthedocs.org/api/v2/embed/?project=sphinx-hoverxref&version=latest&doc=...&section=...

Note

The project and version has to be successfully built on Read the Docs to return the content requested.

Building and serving docs locally

With your documentation’s project configured with the previous settings, you are ready to build and serve the docs from your computer.

Build the documentation with these commands:

cd docs/
make clean
make html

Serve the documentation locally with this command:

python -m http.server --directory _build/html 9000

Now, you can hit http://localhost:9000/ and you should see your documentation here.

Avoid CORS on local backend

When building the documentation locally, the API calls will be blocked by the browser because of CORS (you are hitting the URL http://localhost:9000/ and the API calls are to https://readthedocs.org/).

You can disable this while developing our extension. To do this, you can open Google Chrome with these arguments:

google-chrome-stable --disable-web-security --user-data-dir='/tmp/testing'

If Firefox, you can install this add-ons: Allow CORS: Access-Control-Allow-Origin.

Using a local Read the Docs instance

You can install Read the Docs locally following these instructions. Although, it may be too complicated just to retrieve the same content that you could have in https://readthedocs.org.

To make the extension to work, you will need to define this setting in your conf.py file:

hoverxref_api_host = 'http://dev.readthedocs.io:8000'

Tip

The value of this setting should be the same as PUBLIC_API_URL.

Once you have done that, you can just import the project directly in your local instance, and the tooltips should work without problem.

Permanent tooltip to work with CSS

You need to find the selector of the a element that you want to emulate the mouse hover event first, then from the Javascript console, you can force the browser to trigger this event for us. This way, the element is inserted in the DOM and will persist there. Now, you can find the div for the tooltipster and edit the CSS used to render it.

$('#section > p > a').trigger('mouseenter')

Happy hacking!