Full docs for modal dialogues combined with tooltips

Author: humitos

docs/_images/modal-example.png

@@ -0,0 +1,11 @@
+img.example {
+    box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
+    display: block;
+    margin-left: auto;
+    margin-right: auto;
+}
+
+.topic-title {
+    font-size: 150%;
+    font-family: "Roboto Slab","ff-tisa-web-pro","Georgia",Arial,sans-serif;
+}

docs/_images/tooltip-example.png

@@ -224,3 +224,5 @@ def setup(app):
         'confval',  # rolename
         'pair: %s; configuration value',  # indextemplate
     )
+
+    app.add_css_file('css/custom.css')

docs/_static/css/custom.css

@@ -4,10 +4,16 @@ Configuration
 The default settings should be enough for most of the cases.
 For more specific use cases, you can customize these configuration options in your ``conf.py`` file.
 
+.. contents:: Table of contents
+   :local:
+   :backlinks: none
+   :depth: 1
 
 General settings
 ----------------
 
+These settings are global and have effect on both, tooltips and modal dialogues.
+
 .. confval:: hoverxref_type
 
    Description: How to display the embedded content. As a Tooltip or as a Modal dialogue
@@ -86,6 +92,8 @@ General settings
 Tooltipster
 -----------
 
+These settings have effect only in tooltips.
+
 .. confval:: hoverxref_tooltip_api_host
 
    Description: Host URL for the API to retrieve the tooltip content
@@ -156,6 +164,8 @@ Tooltipster
 MicroModal.js
 -------------
 
+These settings have effect only in modal dialogues.
+
 .. confval:: hoverxref_modal_hover_delay
 
    Description: Delay time (in milliseconds) before showing the modal when hover over a ref

docs/conf.py

@@ -1,41 +1,69 @@
 Welcome to sphinx-hoverxref!
 ============================
 
-``sphinx-hoverxref`` is a Sphinx_ extension to add tooltips on the cross references of the documentation embedding the content of the linked section.
+``sphinx-hoverxref`` is a Sphinx_ extension to show a floating window (tooltips or modal dialogues) on the cross references of the documentation embedding the content of the linked section on them. With ``sphinx-hoverxref``, you don't need to click a link to see what's in there.
 
-Online documentation:
-    https://sphinx-hoverxref.readthedocs.io/
+We currently support two different types of floating windows: Tooltip_ and Modal_.
 
-Source code repository (and issue tracker):
-    https://github.com/readthedocs/sphinx-hoverxref/
 
-Badges:
-    |Build| |PyPI version| |Docs badge| |License|
+Tooltip
+-------
+
+By defining :confval:`hoverxref_type <hoverxref_type>` as ``'tooltip'`` (default) you will get a tooltip when hover references.
+
+.. figure:: _images/tooltip-example.png
+   :width: 75%
+   :class: example
+
+
+Modal
+-----
+
+By defining :confval:`hoverxref_type <hoverxref_type>` as ``'modal'`` you will get a modal when hover references.
+
+.. image:: _images/modal-example.png
+   :width: 75%
+   :class: example
 
 
 Usage
 -----
 
-To show a tooltip on a reference, use the role ``hoverxref`` to link to any document or section.
+To show a floating window on a reference, use the role ``hoverxref`` to link to any document or section.
 
-Writing this reStructuredText:
+Writing this reStructuredText in your document:
 
 .. code-block:: rst
 
-   This will :hoverxref:`show a tooltip <hoverxref:hoverxref>` in the linked words.
+   This will :hoverxref:`show a floating window <hoverxref:hoverxref>` in the linked words.
 
-will render to:
+it will be rendered to:
 
-This will :hoverxref:`show a tooltip <hoverxref:hoverxref>` in the linked words.
+This will :hoverxref:`show a floating window <hoverxref:hoverxref>` in the linked words.
 
 .. tip::
 
    This new ``hoverxref`` role is an alias of the ``ref`` role and works in the same.
-   See :ref:`usage:usage` for more detailed information about and other examples.
+   See :ref:`usage:usage` for more detailed information about this and other examples.
 
 
 ----
 
+Reference
+---------
+
+
+Online documentation:
+    https://sphinx-hoverxref.readthedocs.io/
+
+Source code repository (and issue tracker):
+    https://github.com/readthedocs/sphinx-hoverxref/
+
+Badges:
+    |Build| |PyPI version| |Docs badge| |License|
+
+
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents

docs/configuration.rst

@@ -32,7 +32,7 @@ To do this, add this extension to your Sphinx's extensions in the ``conf.py`` fi
 
 
 After installing the package and adding the extension in the ``conf.py`` file,
-you can use ``:hoverxref:`` role to show a tooltip when hovering with the mouse.
+you can use ``:hoverxref:`` role to show a tooltip [#]_ when hovering with the mouse.
 
 .. warning::
 
@@ -47,3 +47,5 @@ See :ref:`usage:usage` for more use cases and :ref:`configuration:configuration`
 
 
 .. _Read the Docs: https://readthedocs.org/
+
+.. [#] we use tooltips as a generic word, but we refer to both, tooltips and modal dialogues

docs/index.rst

@@ -2,7 +2,7 @@ Usage
 =====
 
 This extension defines a custom role called ``:hoverxref:``.
-When this role is used, it will show a tooltip when the ``hover`` mouse event is triggered,
+When this role is used, it will show a tooltip [#]_ when the ``hover`` mouse event is triggered,
 and will embed the content of the document/section the link is pointing to, into the tooltip's content.
 
 ``:hoverxref:`` role uses Sphinx's internals reference resolution to find out where the link points to.
@@ -15,11 +15,11 @@ Simplest usage example,
 
 .. code-block:: rst
 
-   This will :hoverxref:`show a tooltip <hoverxref:section>` in the linked words to ``hoverxref``.
+   This will :hoverxref:`show a tooltip <hoverxref:hoverxref>` in the linked words to ``hoverxref``.
 
 will render to this:
 
-This will :hoverxref:`show a tooltip <hoverxref:section>` in the linked words to ``hoverxref``.
+This will :hoverxref:`show a tooltip <hoverxref:hoverxref>` in the linked words to ``hoverxref``.
 
 
 Tooltip on custom object
@@ -122,3 +122,5 @@ Show a :hoverxref:`tooltip with Mathjax <mathjax:Mathjax>` formulas.
 
 .. _sphinx-tabs: https://github.com/djungelorm/sphinx-tabs
 .. _mathjax: http://www.sphinx-doc.org/es/master/usage/extensions/math.html#module-sphinx.ext.mathjax
+
+.. [#] we use tooltips as a generic word, but we refer to both, tooltips and modal dialogues