Add some intersphinx external examples and minor details

Author: humitos

Diff for: docs/conf.py

@@ -55,14 +55,23 @@
 intersphinx_mapping = {
     'readthedocs': ('https://docs.readthedocs.io/en/stable/', None),
     'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+    'sympy': ('https://docs.sympy.org/latest/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'python': ('https://docs.python.org/3/', None),
 }
 hoverxref_intersphinx = [
     'readthedocs',
     'sphinx',
+    'sympy',
+    'numpy',
+    'python',
 ]
 hoverxref_intersphinx_types = {
     'readthedocs': 'modal',
     'sphinx': 'tooltip',
+    'sympy': 'tooltip',
+    'numpy': 'tooltip',
+    'python': 'tooltip',
 }
 
 # Used when building the documentation from the terminal and using a local Read

Diff for: docs/configuration.rst

@@ -101,8 +101,9 @@ These settings are global and have effect on both, tooltips and modal dialogues.
 
    .. warning::
 
-      The Sphinx's target project **must be hosted on Read the Docs** to work.
-      This is a current limitation that we hope to remove in the future.
+      The Sphinx's target project **must be hosted on Read the Docs** to work or,
+      be one of the allowed external projects:
+      currently CPython, SymPy, NumPy are supported.
 
 .. confval:: hoverxref_intersphinx_types
 

Diff for: docs/installation.rst

@@ -37,8 +37,8 @@ you can use ``:hoverxref:`` role to show a tooltip [#]_ when hovering with the m
 .. warning::
 
    This extension **requires a backend server** to retrieve the tooltip content.
-   Currently only `Read the Docs`_ is supported,
-   so it will only work if your documentation is hosted on Read the Docs.
+   Currently, only `Read the Docs`_ is supported as backend server.
+   Take into account that your documentation has to be hosted on Read the Docs for this extension to work.
 
 If you prefer to apply this behavior to *all* your ``:ref:`` in your documentation,
 you can use the config :confval:`hoverxref_auto_ref`.

Diff for: docs/usage.rst

@@ -7,9 +7,7 @@ and will embed the content of the document/section the link is pointing to, into
 
 ``:hoverxref:`` role uses Sphinx's internals reference resolution to find out where the link points to.
 So, the way of referencing the section works in the same way as the ``:ref:`` standard role.
-See `Sphinx's ref role documentation`_ for more information.
-
-.. _Sphinx's ref role documentation: https://www.sphinx-doc.org/en/stable/usage/restructuredtext/roles.html#cross-referencing-arbitrary-locations
+See :ref:`Sphinx's ref role documentation <sphinx:ref-role>` for more information.
 
 Simplest usage example,
 
@@ -42,14 +40,23 @@ Show a tooltip for :doc:`Read the Docs automation rules <readthedocs:automation-
 
 .. note::
 
-   Keep in mind that the linked project should be hosted at Read the Docs.
-   This is a limitation that will be removed in the future.
+   Keep in mind that the linked project should be hosted at Read the Docs or,
+   be one of the allowed external projects:
+   currently CPython, SymPy, NumPy are supported.
+
+
+Example with projects not hosted on Read the Docs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Show a tooltip for CPython documentation: :py:mod:`webbrowser <webbrowser>`.
+* Show a tooltip for SymPy documentation: :py:class:`sympy.functions.combinatorial.numbers.tribonacci <sympy.functions.combinatorial.numbers.tribonacci>`.
+* Show a tooltip for NumPy documentation: :py:class:`numpy.single <numpy.single>`.
 
 
 Tooltip on custom object
 ------------------------
 
-Sphinx has the ability to define custom objects (via `Sphinx.add_object_type`_).
+Sphinx has the ability to define custom objects (via :py:meth:`Sphinx.add_object_type <sphinx.application.Sphinx.add_object_type>`).
 ``hoverxref`` can also show a tooltip on these objects if desired.
 You need to tell ``hoverxref`` which are the roles where the tooltip has to appear on.
 To do this, use :confval:`hoverxref_roles <hoverxref_roles>` config.
@@ -119,9 +126,9 @@ These actions are usually calling a Javascript function.
 
 .. warning::
 
-   Note that Sphinx>3.5 adds `a feature to only include JS/CSS in pages where they are used`_ instead of in all the pages.
+   Note that Sphinx>=3.5 adds `a feature to only include JS/CSS in pages where they are used`_ instead of in all the pages.
    This `may affect the rendering of tooltips`_ that includes content requiring extra rendering steps.
-   **Make sure you are using Sphinx 3.4.x or >=4.1.x** if you require rendering this type of content in your tooltips.
+   **Make sure you are using Sphinx <=3.4.x or >=4.1.x** if you require rendering this type of content in your tooltips.
 
    .. _a feature to only include JS/CSS in pages where they are used: https://github.com/sphinx-doc/sphinx/pull/8631
    .. _may affect the rendering of tooltips: https://github.com/sphinx-doc/sphinx/issues/9115
@@ -151,8 +158,6 @@ To render a tooltip where its contents has a ``mathjax`` you need to enable :con
 Show a :hoverxref:`tooltip with Mathjax <mathjax:Mathjax>` formulas.
 
 
-.. _Sphinx.add_object_type: https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_object_type
-
 .. _sphinx-tabs: https://github.com/djungelorm/sphinx-tabs
 .. _mathjax: http://www.sphinx-doc.org/es/master/usage/extensions/math.html#module-sphinx.ext.mathjax