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.
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:
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
hoverxref_api_host = 'http://dev.readthedocs.io:8000'
The value of this setting should be the same as
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,
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')