docs: improve cross-referencing with intersphinx

.gitignore

@@ -71,7 +71,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-
 # PyBuilder
 target/
 
@@ -129,12 +128,10 @@ dmypy.json
 # Pyre type checker
 .pyre/
 
-
 *.swp
 
 _build
 
-
 # autoapi stuff - may be bad to ignore this idk
 autoapi
 
@@ -145,3 +142,6 @@ docs/examples/*.ipynb
 docs/examples/*.gif
 docs/*.ipynb
 docs/gallery
+
+# Test output
+animation-*.gif

docs/Backends.rst

@@ -19,31 +19,31 @@ the `Jupyter Magic <https://ipython.readthedocs.io/en/stable/interactive/magics.
 Further options
 ---------------
 
-If you want to use a non-ipympl backend in a Jupyter Notebook but still want ``ipywidgets`` style sliders then you have a few options.
+If you want to use a non-ipympl backend in a Jupyter Notebook but still want :doc:`ipywidgets <ipywidgets:index>` style sliders then you have a few options.
 
-* With ``interactive_plot`` and ``interactive_hist`` you can pass ``force_ipywidgets=True``
+* With :func:`.interactive_plot` and :func:`.interactive_hist` you can pass ``force_ipywidgets=True``
 
-.. code-block:: python
+    .. code-block:: python
 
-    %matplotlib qt
-    import numpy as np
-    from mpl_interactions import interactive_plot
+        %matplotlib qt
+        import numpy as np
+        from mpl_interactions import interactive_plot
 
-    x = np.linspace(0,np.pi,100)
-    tau = np.linspace(1,10, 100)
-    beta = np.linspace(.001,1)
-    def f(x, tau, beta):
-        return np.sin(x*tau)*x**beta
-    fig, ax, sliders = interactive_plot(f, x=x, tau = tau, beta = beta, force_ipywidgets=True)
+        x = np.linspace(0,np.pi,100)
+        tau = np.linspace(1,10, 100)
+        beta = np.linspace(.001,1)
+        def f(x, tau, beta):
+            return np.sin(x*tau)*x**beta
+        fig, ax, sliders = interactive_plot(f, x=x, tau = tau, beta = beta, force_ipywidgets=True)
 
-This will result in sliders in the notebook, but the plot will be in a ``qt`` window:
+    This will result in sliders in the notebook, but the plot will be in a ``qt`` window:
 
-.. image:: _static/images/force-ipywidgets.png
+    .. image:: _static/images/force-ipywidgets.png
 
 
 * You can also explicitly set whether to use Matplotlib sliders or not with the ``use_ipywidgets`` 
-argument :meth:`~mpl_interactions.interactive_plot`. If ``None`` then the function will try to infer whether
-to use ipywidgets or not. By setting the argument to ``False`` then you will be able to use Matplotlib sliders in the notebook.
+  argument :func:`.interactive_plot`. If `None` then the function will try to infer whether
+  to use ipywidgets or not. By setting the argument to `False`, you will be able to use Matplotlib sliders in the notebook.
 
 
 .. code-block:: python

docs/Contributing.rst

@@ -51,7 +51,7 @@ Also feel free to ask for help/advice on the relevant Github `issue <https://git
 Documentation
 -------------
 
-For the most part the Documentation is generated from the Notebooks in the `examples` folder. So to write new
+For the most part the Documentation is generated from the Notebooks in the ``examples`` folder. So to write new
 examples work in a notebook in the ``examples`` directory. When the docs are generated then they will be
 converted to html via `nbsphinx <https://nbsphinx.readthedocs.io/en/latest/>`_. 
 

docs/Installation.rst

@@ -5,11 +5,19 @@ Installation
 User install
 ------------
 To install simply run:
-``pip install mpl_interactions``
 
-The above only has Matplotlib as a dependency. If you plan on using ``mpl_interactions`` in a Jupyter Notebook or JupyterLab then you should
-install with ``pip install mpl_interactions[jupyter]`` this will install `ipympl <https://github.com/matplotlib/ipympl>`_ and ipywidgets for you.
-If you use JupyterLab it is significantly easier get working for JupyterLab 3+
+.. code-block::
+
+   pip install mpl-interactions
+
+The above only has Matplotlib as a dependency. If you plan on using `mpl_interactions` in a Jupyter Notebook or JupyterLab then you should install with
+
+.. code-block::
+
+   pip install mpl_interactions[jupyter]
+
+This will install `ipympl <https://github.com/matplotlib/ipympl>`_ and :doc:`ipywidgets <ipywidgets:index>` for you.
+If you use JupyterLab it is significantly easier get working for JupyterLab 3+.
 
 Setup for Jupyterlab 3+
 ----------------------------------
@@ -46,4 +54,4 @@ First create your own fork of https://github.com/ianhi/mpl-interactions.
 
    git clone <your fork>
    cd mpl-interactions
-   pip install -e ".[dev, doc, test]"
+   pip install -e ".[dev]"

docs/Makefile

@@ -3,11 +3,16 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -T --color
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
+ifdef ignore-warnings
+else
+	SPHINXOPTS += -W --keep-going
+endif
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_templates/module.rst_t

@@ -0,0 +1,8 @@
+{%- if show_headings and not separate %}
+{{ basename.split(".")[-1] | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}

docs/_templates/package.rst_t

@@ -0,0 +1,45 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{{ pkgname.split(".")[-1] | e | heading }}
+
+{%- if modulefirst and not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if not modulefirst and not is_namespace %}
+
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if submodules or subpackages %}
+.. rubric:: Submodules and Subpackages
+{% endif %}
+
+{%- if subpackages %}
+
+{{ toctree(subpackages) }}
+{% endif %}
+{%- if submodules %}
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{%- else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- [submodule, "module"] | join(" ") | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{% endif %}

docs/_templates/toc.rst_t

@@ -0,0 +1,7 @@
+{{ header | heading }}
+
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}

docs/compare-to-ipywidgets.rst

@@ -17,7 +17,7 @@ expects to be shown only once, then updated with Matplotlib methods as controls
 multiple new figures---or recreate the entire plot---every time a slider value changes. 
 
 It is possible to get around these performance issues by using the ``interact`` function and setting the called function to use Matplotlib updating methods 
-(such as ``line.set_data``). However in this case, not only do you need to remember how to do this, but over time you will find you are repeating yourself.
+(such as :meth:`~matplotlib.lines.Line2D.set_data`). However in this case, not only do you need to remember how to do this, but over time you will find you are repeating yourself.
 Reducing these performance barriers was the initial motivation for the mpl_interactions library, and also brings us to the reason of convenience.
 
 Portability
@@ -51,8 +51,8 @@ Differences in generated widgets
 Tuple of floats
 """""""""""""""""""
 
-Both mpl_interactions and ipywidgets will generate a slider. However, mpl_interactions will use ``np.linspace``
-and ipywidgets will use ``np.arange``.
+Both mpl_interactions and ipywidgets will generate a slider. However, mpl_interactions will use `numpy.linspace`
+and ipywidgets will use `numpy.arange`.
 
 
 Here is a comparison of the generated widget for ``two_tuple = (1., 5)`` and ``three_tuple = (0., 1250, 100)``:
@@ -91,7 +91,7 @@ NumPy array or list
 """""""""""""""""""
 ipywidgets will assume a NumPy array or list are categoricals. mpl_interactions will attempt to make a slider for the values.
 
-For example, here is what ipywidgets and mpl_interactions will create for ``np.linspace(-5,5,100)``:
+For example, here is what ipywidgets and mpl_interactions will create for `np.linspace(-5,5,100) <numpy.linspace>`:
 
 **mpl_interactions**