Use intersphinx everywhere.

Author: bwoodsend

docs/source/Figures.rst

@@ -1,24 +1,24 @@
 Figures
 ==================
 
-Figures, typically abbreviated to `figs`, are the window that you plot into. This
-section outlines:
+Figures, typically abbreviated to ``fig``, are the window that you plot into.
+This section outlines:
 
 * Their creation.
 * General figure management.
 * Functions for controlling the camera position.
 * Screenshotting the figure contents to a frozen image (file).
-* Embedding a figure into PyQt5.
+* Embedding a figure into PyQt5_.
 
 Overview
 --------
 
-Some of this is handled automatically. There is a global "current working figure".
-This can be get and set using ``vpl.gcf()`` and ``vpl.scf(fig)``. If it doesn't
+Some of this is handled automatically. There is a global *current working figure*.
+This can be get and set using `gcf()` and `scf(fig) <scf>`. If it doesn't
 exist then it is automatically created. Each plot command will add itself to the
 current working figure unless explicitly told not by setting ``fig=None`` or
 ``fig=alternative_fig`` in the plot command. The figure is shown using
-``vpl.show()`` or ``fig.show()``. After the shown figure is closed it ceases to
+`vtkplotlib.show` or ``fig.show()``. After the shown figure is closed it ceases to
 be the current working figure but you can use it by referencing it explicitly.
 Figures can be reshown indefinitely and should be exactly as you left them on
 close.
@@ -35,7 +35,7 @@ show
 figure
 -----------------
 
-.. autoclass:: vtkplotlib.figure
+.. autofunction:: vtkplotlib.figure
 
 
 --------------

docs/source/Interactive.rst

@@ -1 +1,6 @@
+.. py:currentmodule:: vtkplotlib.interactive
+
+.. module:: vtkplotlib.i
+
 .. automodule:: vtkplotlib.interactive
+

docs/source/Plots.rst

@@ -46,6 +46,7 @@ polygon
 scalar_bar
 ---------------------
 
+.. py:function:: vtkplotlib.color_bar
 .. autofunction:: vtkplotlib.scalar_bar
 
 
@@ -110,6 +111,6 @@ legend
 custom plots using PolyData
 ---------------------------
 
-.. autofunction:: vtkplotlib.PolyData
+.. autoclass:: vtkplotlib.PolyData
 
 

docs/source/conf.py

@@ -15,6 +15,7 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
+from sphinx.application import Sphinx
 
 # -- Project information -----------------------------------------------------
 
@@ -43,6 +44,7 @@
     'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
     'sphinx.ext.githubpages',
+    'sphinx.ext.intersphinx',
     'sphinx_copybutton',
     'm2r2',
     'sphinx_rtd_theme_configuration',
@@ -89,11 +91,6 @@
 #
 # html_theme_options = {}
 
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 #
@@ -219,9 +216,56 @@ def add_url(name, url):
 .. _namegenerator: https://pypi.org/project/namegenerator/
 """
 
+rst_prolog = """
+.. py:currentmodule:: vtkplotlib
+"""
+
 # -- Add this file for Google search console ----------
 html_extra_path = ["google77eb9775385691af.html"]
 
 # --- Option for autosectionlabel --------
 
 autosectionlabel_prefix_document = True
+
+# --- Intersphinx cross refrerneces ---
+
+# Warn if a cross reference is not found.
+nitpicky = True
+
+# Other projects' website roots so that they can be cross referenced.
+intersphinx_mapping = {
+    'python': ('http://docs.python.org/3', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/', None),
+    'PyQt5': ('https://www.riverbankcomputing.com/static/Docs/PyQt5/', None),
+    'wxPython': ('https://docs.wxpython.org/', None),
+    'matplotib': ('https://matplotlib.org', None),
+    'pillow': ('https://pillow.readthedocs.io/en/stable/', None),
+}
+
+
+def setup(app):
+    # type: (Sphinx) -> None
+
+    # PyQt5 has all its cross reference targets in a special :sip: domain which
+    # needs to be registered to be used. Don't ask me how this works. It's
+    # mostly guess work and copy/paste from sphinx.domains.c.CDomain.
+
+    import sphinx.roles
+    from sphinx.domains import Domain, ObjType, _
+
+    class SIPDomain(Domain):
+        name = "sip"
+        label = "sip"
+        object_types = {
+            key: ObjType(_(key), key, 'data', 'identifier', 'type')
+            for key in "attribute class enum member method module signal".split()
+        }
+
+    app.add_domain(SIPDomain)
+    for key in SIPDomain.object_types:
+        app.add_role_to_domain("sip", key, sphinx.roles.XRefRole())
+
+
+# Set the default interpretation of `foo` to :any:`foo`.
+default_role = "any"

docs/source/index.rst

@@ -3,6 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+.. module:: vtkplotlib
+
 Welcome to vtkplotlib's documentation!
 ======================================
 

docs/source/lookup_example.rst

@@ -2,6 +2,8 @@
 Looking up original data
 ========================
 
+.. py:currentmodule:: vtkplotlib.interactive
+
 The coordinates given by :attr:`pick.point` interpolate between vertices you
 have provided. If you require the nearest user-provided coordinate then you must
 implement this yourself.
@@ -62,7 +64,7 @@ Or, for time-critical applications, using a KDTree from either
 
     fig.show()
 
-Note that having a `MouseMoveEvent` which modifies the contents of a figure and
+Note that having a ``MouseMoveEvent`` which modifies the contents of a figure and
 therefore requires ``fig.update()`` to be called for every such event requires a
 lot of processing power. A better option is to use an output outside of the
-renderer such as a :meth:`QtWidgets.QLabel`.
+renderer such as a `PyQt5.QtWidgets.QLabel`.

docs/source/quickstart.rst

@@ -161,7 +161,7 @@ Line plots:
     import numpy as np
 
     # Create some kind of wiggly shape
-    # use ``vpl.zip_axes`` to combine (x, y, z) axes
+    # use ``vpl.zip_axes()`` to combine (x, y, z) axes
     t = np.linspace(0, 2 * np.pi, 300)
     points = vpl.zip_axes(np.cos(2 * t),
                           np.sin(3 * t),
@@ -196,7 +196,7 @@ the first.
 Mesh plots:
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-.. autoclass:: vtkplotlib.plots.MeshPlot.MeshPlot
+.. autofunction:: vtkplotlib.mesh_plot
     :noindex:
 
 

docs/source/super_callbacks.rst

@@ -2,16 +2,18 @@
 Super Callbacks
 ***************
 
-The methods :meth:`get_super_callback` and :meth:`call_super_callback` get and
+.. py:currentmodule:: vtkplotlib.interactive
+
+The methods :func:`get_super_callback` and :func:`call_super_callback` get and
 call VTK's original responses to user interactions which may have been
 overwritten. See :ref:`Interactive:Super Callbacks?` for why you need them and
 where to use them.
 
-.. autofunction:: vtkplotlib.interactive.get_super_callback()
+.. autofunction:: get_super_callback
 
-.. autofunction:: vtkplotlib.interactive.call_super_callback()
+.. autofunction:: call_super_callback
 
-.. autoexception:: vtkplotlib.interactive.SuperError()
+.. autoexception:: SuperError
     :show-inheritance:
 
-.. autofunction:: vtkplotlib.interactive.null_super_callback()
+.. autofunction:: null_super_callback

vtkplotlib/__init__.py

@@ -67,8 +67,8 @@
 def quick_test_plot(fig="gcf"):
     """A quick laziness function to create 30 random spheres.
 
-    :param fig: The figure to plot into, can be None, defaults to :meth:`vtkplotlib.gcf`.
-    :type fig: :class:`vtkplotlib.figure`, :class:`vtkplotlib.QtFigure`, optional
+    :param fig: The figure to plot into, use `None` for no figure, defaults to the output of `vtkplotlib.gcf()`.
+    :type fig: :class:`~vtkplotlib.figure` or :class:`~vtkplotlib.QtFigure`
 
     .. code-block:: python
 

vtkplotlib/_image_io.py

@@ -43,24 +43,24 @@ def read(path, raw_bytes=None, format=None, convert_to_array=True):
     """Read an image from a file using one of VTK's ``vtkFormatReader`` classes
     where ``Format`` is replaced by JPEG, PNG, BMP or TIFF.
 
-    :param path: Filename or file handle or ``None`` if using the **raw_bytes** argument.
+    :param path: Filename or file handle or `None` if using the **raw_bytes** argument.
     :type path: str, os.PathLike, io.BytesIO
 
-    :param raw_bytes: Image compressed binary data, defaults to ``None``.
-    :type raw_bytes: bytes, optional
+    :param raw_bytes: Image compressed binary data.
+    :type raw_bytes: bytes
 
-    :param format: Image format extension (e.g. jpg), not needed if format can be determined from **path**, defaults to ``None``.
-    :type format: str, optional
+    :param format: Image format extension (e.g. jpg). This should never be needed.
+    :type format: str
 
-    :param convert_to_array: If true, convert to numpy, otherwise leave as vtkImageData, defaults to ``True``.
-    :type convert_to_array: bool, optional
+    :param convert_to_array: If true, convert to `numpy.ndarray`, otherwise leave as vtkImageData_.
+    :type convert_to_array: bool
 
     :return: Read image.
-    :rtype: np.ndarray or `vtkImageData`_
+    :rtype: `numpy.ndarray` or `vtkImageData`_
 
     The file format can be determined automatically from the **path** suffix or the beginning
     of **raw_bytes**. **format** can be any of JPEG, PNG, TIFF, BMP. It is case
-    insensitive, tolerant to preceding '.'s e.g. ``format=".jpg"`` and
+    insensitive, tolerant to preceding ``'.'`` e.g. ``format=".jpg"`` and
     understands the aliases JPG \u21d4 JPEG and TIF \u21d4 TIFF.
 
     The following demonstrates how to use pseudo file objects to avoid temporary
@@ -70,7 +70,7 @@ def read(path, raw_bytes=None, format=None, convert_to_array=True):
 
         import vtkplotlib as vpl
 
-        # Link you're image url here
+        # Link your image url here
         url = "https://raw.githubusercontent.com/bwoodsend/vtkplotlib/master/vtkplotlib/data/icons/Right.jpg"
 
         # You can make the url request with either:
@@ -81,7 +81,7 @@ def read(path, raw_bytes=None, format=None, convert_to_array=True):
         # import requests
         # raw_bytes = requests.get(url).content
 
-        # Pass the bytes to :meth:`read` using:
+        # Pass the bytes to `read()` using:
         image = vpl.image_io.read(path=None, raw_bytes=raw_bytes)
 
         # Visualize using matplotlib.
@@ -190,22 +190,22 @@ def write(arr, path, format=None, quality=95):
     """Write an image from a file using one of VTK's ``vtkFormatWriter`` classes
     where ``Format`` is replaced by JPEG or PNG.
 
-    :param arr: **arr** can be a `vtkImageData`_ or a numpy array.
-    :type arr: np.ndarray
+    :param arr: An image array.
+    :type arr: `numpy.ndarray` or `vtkImageData`_
 
     :param path: File path to write to.
-    :type path: str, os.Pathlike, io.BytesIO,
+    :type path: str or os.PathLike or io.BytesIO
 
-    :param format: Image format extension (e.g. jpg), not needed if format can be determined from **path**, defaults to ``None``.
-    :type format: str, optional
+    :param format: Image format extension (e.g. jpg), not needed if format can be determined from **path**.
+    :type format: str
 
-    :param quality: Lossy compression quality, only applicable to JPEGs, defaults to 95.
-    :type quality: int from 0 to 100, optional
+    :param quality: Lossy compression quality (only applicable to JPEGs) between 0 to 100.
+    :type quality: int
 
-    :return: The raw image binary if ``path is None``, ``NotImplemented`` if the filetype is unknown. Otherwise no return value.
+    :return: The raw image binary if ``path is None``, `NotImplemented` if the filetype is unknown. Otherwise no return value.
     :rtype: bytes
 
-    See :meth:`read` for more information.
+    See `read` for more information.
 
     .. note::
 
@@ -247,7 +247,7 @@ def write(arr, path, format=None, quality=95):
 def vtkimagedata_to_array(image_data):
     """Convert a vtkImageData to numpy array.
 
-    .. seealso:: :meth:`vtkimagedata_from_array` for the reverse.
+    .. seealso:: `vtkimagedata_from_array` for the reverse.
 
     """
     points = vtk_to_numpy(image_data.GetPointData().GetScalars())
@@ -265,11 +265,11 @@ def vtkimagedata_to_array(image_data):
 def vtkimagedata_from_array(arr, image_data=None):
     """Convert a numpy array to a vtkImageData.
 
-    :param arr: Array of colors.
-    :type arr: np.ndarray with dtype ``np.uint8``
+    :param arr: An ``uint8`` array of colors.
+    :type arr: numpy.ndarray
 
-    :param image_data: An image data to write into, a new one is created if not specified, defaults to ``None``.
-    :type image_data: `vtkImageData`_, optional
+    :param image_data: An image data to write into, a new one is created if not specified.
+    :type image_data: `vtkImageData`_
 
     :return: A VTK image.
     :rtype: `vtkImageData`_
@@ -278,9 +278,9 @@ def vtkimagedata_from_array(arr, image_data=None):
     ``(m, n, 1)`` for greyscale, ``(m, n, 3)`` for RGB, or ``(m, n, 4)`` for
     RGBA.
 
-    .. seealso:: :meth:`vtkimagedata_to_array` for the reverse.
+    .. seealso:: `vtkimagedata_to_array` for the reverse.
 
-    .. seealso:: :meth:`as_vtkimagedata` for converting from other types.
+    .. seealso:: `as_vtkimagedata` for converting from other types.
 
     """
     assert arr.dtype == np.uint8
@@ -308,20 +308,20 @@ def trim_image(arr, background_color, crop_padding):
     background.
 
     :param arr: An image array.
-    :type arr: 3D np.ndarray
+    :type arr: numpy.ndarray
 
     :param background_color: The color of the portions to crop away.
-    :type background_color: Strictly an (r, g, b) tuple.
+    :type background_color: tuple
 
-    :param crop_padding: Space to leave, in pixels if int, or relative to image size if float.
+    :param crop_padding: Space to leave, in pixels if `int`, or relative to image size if `float`.
     :type crop_padding: int or float
 
-    :return: Smaller image array.
-    :rtype: 3D np.ndarray
+    :return: A smaller image array.
+    :rtype: numpy.ndarray
 
 
     If you don't want your files smaller you can instead use
-    :meth:`vtkplotlib.zoom`.
+    `vtkplotlib.zoom_to_contents`.
 
     """
     if (crop_padding is None) or crop_padding == 0: