hoverxref.extension
===================

.. py:module:: hoverxref.extension


Attributes
----------

.. autoapisummary::

   hoverxref.extension.logger
   hoverxref.extension.CSS_CLASS_PREFIX
   hoverxref.extension.CSS_DEFAULT_CLASS
   hoverxref.extension.CSS_CLASSES
   hoverxref.extension.HOVERXREF_ASSETS_FILES
   hoverxref.extension.TOOLTIP_ASSETS_FILES
   hoverxref.extension.MODAL_ASSETS_FILES
   hoverxref.extension.ASSETS_FILES


Functions
---------

.. autoapisummary::

   hoverxref.extension.copy_asset_files
   hoverxref.extension.setup_domains
   hoverxref.extension.setup_intersphinx
   hoverxref.extension.missing_reference
   hoverxref.extension.setup_theme
   hoverxref.extension.setup_assets_policy
   hoverxref.extension.deprecated_configs_warning
   hoverxref.extension.setup


Module Contents
---------------

.. py:data:: logger

.. py:data:: CSS_CLASS_PREFIX
   :value: 'hxr-'


.. py:data:: CSS_DEFAULT_CLASS
   :value: 'hxr-hoverxref'


.. py:data:: CSS_CLASSES

.. py:data:: HOVERXREF_ASSETS_FILES
   :value: ['js/hoverxref.js_t']


.. py:data:: TOOLTIP_ASSETS_FILES
   :value: ['js/tooltipster.bundle.min.js', 'css/tooltipster.custom.css_t',...


.. py:data:: MODAL_ASSETS_FILES
   :value: ['js/micromodal.min.js', 'css/micromodal.css']


.. py:data:: ASSETS_FILES
   :value: ['js/hoverxref.js_t', 'js/tooltipster.bundle.min.js', 'css/tooltipster.custom.css_t',...


.. py:function:: copy_asset_files(app, exception)

   Copy all assets after build finished successfully.

   Assets that are templates (ends with ``_t``) are previously rendered using
   using all the configs starting with ``hoverxref_`` as a context.


.. py:function:: setup_domains(app, config)

   Override domains respecting the one defined (if any).

   We create a new class by inheriting the Sphinx Domain already defined
   and our own ``HoverXRef...DomainMixin`` that includes the logic for
   ``_hoverxref`` attributes.


.. py:function:: setup_intersphinx(app, config)

   Disconnect ``missing-reference`` from ``sphinx.ext.intershinx``.

   As there is no way to hook into the ``missing_referece`` function to add
   some extra data to the docutils node returned by this function, we
   disconnect the original listener and add our custom one.

   https://github.com/sphinx-doc/sphinx/blob/53c1dff/sphinx/ext/intersphinx.py


.. py:function:: missing_reference(app, env, node, contnode)

   Override original ``missing_referece`` to add data into the node.

   We call the original intersphinx extension and add hoverxref CSS classes
   plus the ``data-url`` to the node returned from it.

   Sphinx intersphinx downloads all the ``objects.inv`` and load each of them
   into a "named inventory" and also updates the "main inventory". We check if
   reference is part of any of the "named invetories" the user defined in
   ``hoverxref_intersphinx`` and we add hoverxref to the node **only if** the
   reference is on those inventories.

   See https://github.com/sphinx-doc/sphinx/blob/4d90277c/sphinx/ext/intersphinx.py#L244-L250


.. py:function:: setup_theme(app, exception)

   Auto-configure default settings for known themes.

   Add a small custom CSS file for a specific theme and set hoverxref configs
   (if not overwritten by the user) with better defaults for these themes.


.. py:function:: setup_assets_policy(app, exception)

   Tell Sphinx to always include assets in all HTML pages.


.. py:function:: deprecated_configs_warning(app, exception)

   Log warning message if old configs are used.


.. py:function:: setup(app)

   Setup ``hoverxref`` Sphinx extension.