Optional usage of module instead of module_short when doing backr…

…eferencing (#950)

* checks for right builder

* changed to be a list of blocked builders

* added note in documentation

* Update doc/getting_started.rst

* Update sphinx_gallery/gen_gallery.py

* Update sphinx_gallery/tests/test_gen_gallery.py

* FIX: Test

* use full module

* added prefer_full_module to config

* docu added

* Update doc/configuration.rst

* fixed linting error

* fix windows pipeline error

* instal libiconv

Co-authored-by: Eric Larson <larson.eric.d@gmail.com>

azure-pipelines.yml

@@ -55,7 +55,8 @@ stages:
       displayName: Install OpenGL
     - bash: |
         set -e
-        pip install --user --upgrade pip setuptools wheel
+        python --version
+        python -m pip install --user --upgrade pip setuptools wheel
         pip install --user --upgrade --progress-bar off --upgrade ipython numpy seaborn statsmodels matplotlib sphinx pillow pytest pytest-cov sphinx_rtd_theme joblib "plotly>=4.0" vtk
         pip install --user --upgrade --progress-bar off pyvista mayavi pyqt5
       displayName: Setup pip environment

continuous_integration/azure/install.sh

@@ -26,6 +26,7 @@ if [ "$DISTRIB" == "conda" ]; then
     elif [ "$SPHINX_VERSION" == "dev" ]; then
         # It is a mystery to me why we need black, but we get an error with sphinx that it's needed at the end of the build...
         PIP_DEPENDENCIES="${PIP_DEPENDENCIES} https://api.github.com/repos/sphinx-doc/sphinx/zipball/master black"
+        CONDA_TO_INSTALL="$CONDA_TO_INSTALL libiconv"
     else
         PIP_DEPENDENCIES="${PIP_DEPENDENCIES} sphinx==${SPHINX_VERSION} jinja2<=3.0.3"
     fi

doc/configuration.rst

@@ -28,7 +28,7 @@ file:
 - ``reset_argv`` (:ref:`reset_argv`)
 - ``subsection_order`` (:ref:`sub_gallery_order`)
 - ``within_subsection_order`` (:ref:`within_gallery_order`)
-- ``reference_url`` (:ref:`link_to_documentation`)
+- ``reference_url``, ``prefer_full_module`` (:ref:`link_to_documentation`)
 - ``backreferences_dir``, ``doc_module``, ``exclude_implicit_doc``,
   and ``inspect_global_variables`` (:ref:`references_to_examples`)
 - ``default_thumb_file`` (:ref:`custom_default_thumb`)
@@ -255,8 +255,8 @@ Passing command line arguments to example scripts
 =================================================
 
 By default, Sphinx-Gallery will not pass any command line arguments to example
-scripts.  By setting the ``reset_argv`` option, it is possible to change this
-behavior and pass command line arguments to example scripts.  ``reset_argv``
+scripts. By setting the ``reset_argv`` option, it is possible to change this
+behavior and pass command line arguments to example scripts. ``reset_argv``
 needs to be a Callable that accepts the ``gallery_conf`` and ``script_vars``
 dictionaries as input and returns a list of strings that are passed as
 additional command line arguments to the interpreter.
@@ -406,6 +406,30 @@ point to the directory containing ``searchindex.js``, such as
 If you wish to do the same for ordinary RST documentation,
 see :ref:`plain_rst`.
 
+If you are using inheritance for your documented code and you are experience 
+wrong links in the sense that the links point to the base class of an object 
+instead of the child, the option ``prefer_full_module`` might solve your issue. 
+Have also a look at `the GitHub 
+issue <https://github.com/sphinx-gallery/sphinx-gallery/issues/947>`__
+implementing this option for more context.
+
+To make this work in your documentation you need to include to the 
+configuration
+dictionary within your Sphinx ``conf.py`` file::
+
+    sphinx_gallery_conf = {
+        ...
+        'prefer_full_module':[
+        # a list of regex command of your module where the full module
+        # name should be used for sphinx_gallery instead of the shortend
+        'yourmodule.*+\d{4}',
+        ]
+    }
+
+In the above examples all modules matching the string ``'yourmodule.*+\d{4}'`` 
+would use the full module name when creating the links. All other use the 
+(default) way of linking.
+
 .. _references_to_examples:
 
 Add mini-galleries for API documentation
@@ -482,8 +506,8 @@ instead of any character, if the name is unambiguous you can also write
 ``pyplot.show`` or just ``show``).
 
 The ``add-heading`` option adds a heading for the mini-gallery, which will be a
-default generated message if no string is provided as an argument.  The example
-mini-gallery shown above uses the default heading.  The level of the heading
+default generated message if no string is provided as an argument. The example
+mini-gallery shown above uses the default heading. The level of the heading
 defaults to ``^``, but can be changed using the ``heading-level`` option, which
 accepts a single character (e.g., ``-``). The mini-gallery will only be shown
 if the item (here ``numpy.exp``) is actually used or referred to in an example.
@@ -533,7 +557,7 @@ documentation is done at the module level. We first start with the
 The important directives are ``currentmodule`` where we specify which
 module we are documenting, for our purpose is ``sphinx_gallery``. The
 ``autosummary`` directive is responsible for generating the ``rst``
-files documenting each module.  ``autosummary`` takes the option
+files documenting each module. ``autosummary`` takes the option
 *toctree* which is where the ``rst`` files are saved and *template*
 which is the file that describes how the module ``rst`` documentation
 file is to be constructed, finally we write the modules we wish to
@@ -577,7 +601,7 @@ properly):
 
 - :class:`lst <python:list>`
 - :func:`plt.subplots <matplotlib.pyplot.subplots>`
-- :class:`fig  <matplotlib.figure.Figure>`
+- :class:`fig <matplotlib.figure.Figure>`
 - :class:`ax <matplotlib.axes.Axes>`
 - :meth:`ax.plot <matplotlib.axes.Axes.plot>`
 
@@ -1009,8 +1033,8 @@ dictionary following the pattern below::
          # Required keys
          'org': '<github_org>',
          'repo': '<github_repo>',
-         'branch': '<github_branch>',  # Can be any branch, tag, or commit hash. Use a branch that hosts your docs.
-         'binderhub_url': '<binder_url>',  # Any URL of a binderhub deployment. Must be full URL (e.g. https://mybinder.org).
+         'branch': '<github_branch>', # Can be any branch, tag, or commit hash. Use a branch that hosts your docs.
+         'binderhub_url': '<binder_url>', # Any URL of a binderhub deployment. Must be full URL (e.g. https://mybinder.org).
          'dependencies': '<list_of_paths_to_dependency_files>',
          # Optional keys
          'filepath_prefix': '<prefix>' # A prefix to prepend to any filepaths in Binder links.
@@ -1054,7 +1078,7 @@ binderhub_url (type: string)
 dependencies (type: list)
   A list of paths (relative to ``conf.py``) to dependency files that Binder uses
   to infer the environment needed to run your examples. For example, a
-  ``requirements.txt`` file. These will be copied into a folder   called
+  ``requirements.txt`` file. These will be copied into a folder  called
   ``binder/`` in your built documentation folder. For a list of all the possible
   dependency files you can use, see `the Binder configuration documentation
   <https://mybinder.readthedocs.io/en/latest/config_files.html#config-files>`_.
@@ -1222,7 +1246,7 @@ for hi-dpi/retina displays. Sphinx Gallery supports this via the
     }
 
 that saves a 1x image at the normal figure dpi (usually 100 dpi) and a 2x
-version at twice the density (e.g. 200 dpi).  The default is no extra images
+version at twice the density (e.g. 200 dpi). The default is no extra images
 (``'image_srcset': []``), and you can specify other resolutions if desired as a
 list: ``["2x", "1.5x"]``.
 
@@ -1243,7 +1267,7 @@ This leads to a larger website, but clients that support the ``srcset`` tag will
 download the appropriate-sized images.
 
 Note that the ``.. image-sg`` directive currently ignores other ``.. image``
-directive tags like ``width``, ``height``, and ``align``.  It also only works
+directive tags like ``width``, ``height``, and ``align``. It also only works
 with the *html* and *latex*  builders.
 
 .. _image_scrapers:
@@ -1314,7 +1338,7 @@ feel free to add it to the list above (see discussion
 Using multiple code blocks to create a single figure
 ====================================================
 
-By default, images are scraped following each code block in an example.  Thus,
+By default, images are scraped following each code block in an example. Thus,
 the following produces two plots, with one plot per code block::
 
   # %%
@@ -1332,10 +1356,10 @@ the following produces two plots, with one plot per code block::
 
 However, sometimes it can be useful to use multiple code blocks to create a
 single figure, particularly if the figure takes a large number commands that
-would benefit from being interleaved with text blocks.  The optional flag
+would benefit from being interleaved with text blocks. The optional flag
 ``sphinx_gallery_defer_figures`` can be inserted as a comment anywhere in a code
 block to defer the scraping of images to the next code block (where it can be
-further deferred, if desired).  The following produces only one plot::
+further deferred, if desired). The following produces only one plot::
 
   # %%
   # This first code block does not produce any plot
@@ -1471,7 +1495,7 @@ By default, Sphinx-Gallery will reset modules before each example is run.
 The choices for ``reset_modules_order`` are ``before`` (default), ``after``, and
 ``both``. If the last example run in Sphinx-Gallery modifies a module, it is
 recommended to use ``after`` or ``both`` to avoid leaking out a modified module to
-other parts of the Sphinx build process.  For example, set ``reset_modules_order``
+other parts of the Sphinx build process. For example, set ``reset_modules_order``
 to ``both`` in the configuration::
 
     sphinx_gallery_conf = {
@@ -1480,7 +1504,7 @@ to ``both`` in the configuration::
     }
 
 Custom functions can be constructed to have custom functionality depending on
-whether they are called before or after the examples.  See :ref:`custom_reset`
+whether they are called before or after the examples. See :ref:`custom_reset`
 for more information.
 
 Dealing with failing Gallery example scripts
@@ -1630,10 +1654,10 @@ Minimal reported time
 =====================
 
 By default, Sphinx-Gallery logs and embeds in the html output the time it took
-to run each script.  If the majority of your examples runs quickly, you may not
+to run each script. If the majority of your examples runs quickly, you may not
 need this information.
 
-The ``min_reported_time`` parameter can be set to a number of seconds.  The
+The ``min_reported_time`` parameter can be set to a number of seconds. The
 duration of scripts that ran faster than that amount will not be logged nor
 embedded in the html output.
 
@@ -1735,7 +1759,7 @@ From another perspective, take for example the following code block::
 
     print('Hello world')
     a=2
-    a   # this is an expression
+    a  # this is an expression
 
 ``'Hello world'`` would be captured for every ``capture_repr`` setting as this
 is directed to standard output. Further,

sphinx_gallery/docs_resolv.py

@@ -136,7 +136,8 @@ class SphinxDocLinkResolver(object):
         package).
     """
 
-    def __init__(self, doc_url, gallery_dir, relative=False):
+    def __init__(self, config, doc_url, gallery_dir, relative=False):
+        self.config = config
         self.doc_url = doc_url
         self.gallery_dir = gallery_dir
         self.relative = relative
@@ -208,9 +209,12 @@ def _get_index_match(self, first, second):
                     return None
         return match
 
-    def _get_link_type(self, cobj):
+    def _get_link_type(self, cobj, use_full_module=False):
         """Get a valid link and type_, False if not found."""
-        first, second = cobj['module_short'], cobj['name']
+        module_type = 'module_short'
+        if use_full_module:
+            module_type = 'module'
+        first, second = cobj[module_type], cobj['name']
         match = self._get_index_match(first, second)
         if match is None and '.' in second:  # possible class attribute
             first, second = second.split('.', 1)
@@ -273,7 +277,13 @@ def resolve(self, cobj, this_url, return_type=False):
         full_name = cobj['module_short'] + '.' + cobj['name']
         if full_name not in self._link_cache:
             # we don't have it cached
-            self._link_cache[full_name] = self._get_link_type(cobj)
+            use_full_module = False
+            for pattern in self.config['prefer_full_module']:
+                if re.search(pattern, full_name):
+                    use_full_module = True
+                    break
+            self._link_cache[full_name] = self._get_link_type(
+                cobj, use_full_module)
         link, type_ = self._link_cache[full_name]
 
         if self.relative and link is not None:
@@ -312,9 +322,11 @@ def _embed_code_links(app, gallery_conf, gallery_dir):
         try:
             if url is None:
                 doc_resolvers[this_module] = SphinxDocLinkResolver(
+                    app.config.sphinx_gallery_conf,
                     app.builder.outdir, src_gallery_dir, relative=True)
             else:
                 doc_resolvers[this_module] = SphinxDocLinkResolver(
+                    app.config.sphinx_gallery_conf,
                     url, src_gallery_dir)
 
         except (URLError, HTTPError) as e:

sphinx_gallery/gen_gallery.py

@@ -99,6 +99,7 @@ def __call__(self, gallery_conf, script_vars):
     'image_srcset': [],
     'default_thumb_file': None,
     'line_numbers': False,
+    'prefer_full_module': [],
 }
 
 logger = sphinx_compatibility.getLogger('sphinx-gallery')