Docs: minimal docs for links preview addons (#11828)

readthedocs · Dec 9, 2024 · f562a0a · f562a0a
1 parent 380d64b
commit f562a0a
Show file tree

Hide file tree

Showing 6 changed files with 35 additions and 31 deletions.
diff --git a/docs/user/_static/images/addons-link-previews.png b/docs/user/_static/images/addons-link-previews.png
diff --git a/docs/user/_static/images/guides/sphinx-hoverxref-example.png b/docs/user/_static/images/guides/sphinx-hoverxref-example.png
diff --git a/docs/user/addons.rst b/docs/user/addons.rst
@@ -5,9 +5,12 @@ Read the Docs Addons
 They are used in the rendered documentation,
 and can be accessed via hotkeys or on screen UI elements.
 
-:doc:`DocDiff </pull-requests>`
+:doc:`DocDiff </doc-diff>`
     Highlight changed output from pull requests
 
+:doc:`Link previews </link-previews>`
+    See the content the link points to before clicking on it
+
 :doc:`Documentation notification </doc-notifications>`
     Alert users to various documentation states
 
@@ -23,9 +26,6 @@ and can be accessed via hotkeys or on screen UI elements.
 :doc:`Search as you type </server-side-search/index>`
     Get search results faster
 
-:doc:`DocDiff </pull-requests>`
-    Highlight changed output from pull requests
-
 :doc:`Traffic analytics </traffic-analytics>`
     See what pages your users are reading
 
@@ -37,11 +37,7 @@ Configuring Read the Docs Addons
 
 Individual configuration options for each addon are available in :guilabel:`Settings`.
 
-#. Go to the new dashboard:
-
-    * `Community <https://app.readthedocs.org>`_
-    * `Business <https://app.readthedocs.com>`_
-
+#. Go to the new :term:`dashboard`:
 #. Click on a project name.
 #. Go to :guilabel:`Settings`
 #. In the left bar, go to :guilabel:`Addons`.

diff --git a/docs/user/guides/embedding-content.rst b/docs/user/guides/embedding-content.rst
@@ -1,5 +1,3 @@
-.. TODO: Write feature page for hoverxref
-
 How to embed content from your documentation
 ============================================
 
@@ -18,27 +16,10 @@ Contextualized tooltips on documentation pages
 ----------------------------------------------
 
 Tooltips on your own documentation are really useful to add more context to the current page the user is reading.
-You can embed any content that is available via reference in Sphinx, including:
-
-* Python object references
-* Full documentation pages
-* Sphinx references
-* Term definitions
-
-We built a Sphinx extension called ``sphinx-hoverxref`` on top of our Embed API
-you can install in your project with minimal configuration.
-
-Here is an example showing a tooltip when you hover with the mouse a reference:
-
-.. figure:: /_static/images/guides/sphinx-hoverxref-example.png
-   :width: 80%
-   :align: center
-
-   Tooltip shown when hovering on a reference using ``sphinx-hoverxref``.
-
-You can find more information about this extension, how to install and configure it in the `hoverxref documentation`_.
+You can embed any content that is available via an HTML id.
 
-.. _hoverxref documentation: https://sphinx-hoverxref.readthedocs.io/
+We built an addon called :doc:`Link previews </link-previews>` on top of our Embed API
+that you can enable from the addons settings of your project using the :term:`dashboard`.
 
 Inline help on application website
 ----------------------------------

diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -63,6 +63,7 @@ Read the Docs: documentation simplified
 
    /downloadable-documentation
    /doc-diff
+   /link-previews
    /guides/embedding-content
    /server-side-search/index
    /server-side-search/syntax

diff --git a/docs/user/link-previews.rst b/docs/user/link-previews.rst
@@ -0,0 +1,26 @@
+Link previews
+=============
+
+Link previews allows you to see the content of the link you are about to click when you hover over it.
+This gives you the ability to quickly preview where a link points,
+so you can keep your context while reading but learn more from other resources.
+
+.. figure:: /_static/images/addons-link-previews.png
+   :width: 80%
+
+   Example of link previews addon
+
+
+
+Enabling link previews
+----------------------
+
+In your dashboard, you can go to the links preview tag in :guilabel:`Settings > Addons > Link previews` and enable it.
+
+Troubleshooting link previews
+-----------------------------
+
+We perform some heuristic to detect the documentation tool used to generate the page based on its HTML structure.
+This auto-detection may fail, resulting in the content rendered inside the popup being incorrect.
+If you are experimenting this, you can specify the CSS selector for the main content in :guilabel:`Settings > Addons > Advanced`,
+or you can `open an issue in the addons repository <https://github.com/readthedocs/addons>`_ so we improve our heuristic.