Fix some links for docs (#341)

* Fix some links for docs

* Add show to remove output from jupytext and fix module link

* fix more links

* rcParams as :data:

Author: cvanelteren

docs/basics.py

@@ -26,17 +26,17 @@
 #
 # UltraPlot works by `subclassing
 # <https://docs.python.org/3/tutorial/classes.html#inheritance>`__
-# three fundamental matplotlib classes: :class:`ultraplot.figure.Figure` replaces
-# :class:`matplotlib.figure.Figure`, :class:`ultraplot.axes.Axes` replaces :class:`matplotlib.axes.Axes`,
-# and :class:`ultraplot.gridspec.GridSpec` replaces :class:`matplotlib.gridspec.GridSpec`
+# three fundamental matplotlib classes: :class:`~ultraplot.figure.Figure` replaces
+# :class:`matplotlib.figure.Figure`, :class:`~ultraplot.axes.Axes` replaces :class:`matplotlib.axes.Axes`,
+# and :class:`~ultraplot.gridspec.GridSpec` replaces :class:`matplotlib.gridspec.GridSpec`
 # (see this `tutorial
 # <https://matplotlib.org/stable/tutorials/intermediate/gridspec.html>`__
 # for more on gridspecs).
 #
 # To make plots with these classes, you must start with the top-level commands
 # :func:`~ultraplot.ui.figure`, :func:`~ultraplot.ui.subplot`, or :func:`~ultraplot.ui.subplots`. These are
-# modeled after the :func:`~matplotlib.pyplot` commands of the same name. As in
-# :func:`~matplotlib.pyplot`, :func:`~ultraplot.ui.subplot` creates a figure and a single
+# modeled after the :mod:`~matplotlib.pyplot` commands of the same name. As in
+# :mod:`~matplotlib.pyplot`, :func:`~ultraplot.ui.subplot` creates a figure and a single
 # subplot, :func:`~ultraplot.ui.subplots` creates a figure and a grid of subplots, and
 # :func:`~ultraplot.ui.figure` creates an empty figure that can be subsequently filled
 # with subplots. A minimal example with just one subplot is shown below.
@@ -85,6 +85,7 @@
 # fig = uplt.figure(suptitle='Single subplot')  # equivalent to above
 # ax = fig.subplot(xlabel='x axis', ylabel='y axis')
 ax.plot(data, lw=2)
+fig.show()
 
 
 # %% [raw] raw_mimetype="text/restructuredtext"
@@ -95,11 +96,11 @@
 #
 # Similar to matplotlib, subplots can be added to figures one-by-one
 # or all at once. Each subplot will be an instance of
-# :class:`ultraplot.axes.Axes`. To add subplots all at once, use
-# :func:`ultraplot.figure.Figure.add_subplots` (or its shorthand,
-# :func:`ultraplot.figure.Figure.subplots`). Note that under the hood, the top-level
-# UltraPlot command :func:`~ultraplot.ui.subplots` simply calls :class::func:`~ultraplot.ui.figure`
-# followed by :func:`ultraplot.figure.Figure.add_subplots`.
+# :class:`~ultraplot.axes.Axes`. To add subplots all at once, use
+# :func:`~ultraplot.figure.Figure.add_subplots` (or its shorthand,
+# :func:`~ultraplot.figure.Figure.subplots`). Note that under the hood, the top-level
+# UltraPlot command :func:`~ultraplot.ui.subplots` simply calls :func:`~ultraplot.ui.figure`
+# followed by :func:`~ultraplot.figure.Figure.add_subplots`.
 #
 # * With no arguments, :func:`~ultraplot.figure.Figure.add_subplots` returns a subplot
 #   generated from a 1-row, 1-column :class:`~ultraplot.gridspec.GridSpec`.
@@ -109,13 +110,13 @@
 # * With `array`, :func:`~ultraplot.figure.Figure.add_subplots` returns an arbitrarily
 #   complex grid of subplots from a :class:`~ultraplot.gridspec.GridSpec` with matching
 #   geometry. Here `array` is a 2D array representing a "picture" of the subplot
-#   layout, where each unique integer indicates a `~matplotlib.gridspec.GridSpec`
+#   layout, where each unique integer indicates a :class:`~matplotlib.gridspec.GridSpec`
 #   slot occupied by the corresponding subplot and ``0`` indicates an empty space.
 #   The returned subplots are contained in a :class:`~ultraplot.gridspec.SubplotGrid`
 #   (:ref:`see below <ug_subplotgrid>` for details).
 #
-# To add subplots one-by-one, use the :func:`ultraplot.figure.Figure.add_subplot`
-# command (or its shorthand :func:`ultraplot.figure.Figure.subplot`).
+# To add subplots one-by-one, use the :func:`~ultraplot.figure.Figure.add_subplot`
+# command (or its shorthand :func:`~ultraplot.figure.Figure.subplot`).
 #
 # * With no arguments, :func:`~ultraplot.figure.Figure.add_subplot` returns a subplot
 #   generated from a 1-row, 1-column :class:`~ultraplot.gridspec.GridSpec`.
@@ -124,7 +125,7 @@
 #   as in matplotlib. Note that unlike matplotlib, the geometry must be compatible
 #   with the geometry implied by previous :func:`~ultraplot.figure.Figure.add_subplot` calls.
 # * With a :class:`~matplotlib.gridspec.SubplotSpec` generated by indexing a
-#   :class:`ultraplot.gridspec.GridSpec`, :func:`~ultraplot.figure.Figure.add_subplot` returns a
+#   :class:`~ultraplot.gridspec.GridSpec`, :func:`~ultraplot.figure.Figure.add_subplot` returns a
 #   subplot at the corresponding location. Note that unlike matplotlib, only
 #   one :func:`~ultraplot.figure.Figure.gridspec` can be used with each figure.
 #
@@ -156,6 +157,7 @@
 fig.format(
     suptitle="Simple subplot grid", title="Title", xlabel="x axis", ylabel="y axis"
 )
+fig.show()
 # fig.save('~/example1.png')  # save the figure
 # fig.savefig('~/example1.png')  # alternative
 
@@ -181,6 +183,7 @@
     ylabel="ylabel",
 )
 axs[2].plot(data, lw=2)
+fig.show()
 # fig.save('~/example2.png')  # save the figure
 # fig.savefig('~/example2.png')  # alternative
 
@@ -203,6 +206,7 @@
     suptitle="Really complex subplot grid", xlabel="xlabel", ylabel="ylabel", abc=True
 )
 axs[0].plot(data, lw=2)
+fig.show()
 # fig.save('~/example3.png')  # save the figure
 # fig.savefig('~/example3.png')  # alternative
 
@@ -222,6 +226,7 @@
 fig.format(
     suptitle="Subplot grid with a GridSpec", xlabel="xlabel", ylabel="ylabel", abc=True
 )
+fig.show()
 # fig.save('~/example4.png')  # save the figure
 # fig.savefig('~/example4.png')  # alternative
 
@@ -234,7 +239,7 @@
 # If you create subplots all-at-once with e.g. :func:`~ultraplot.ui.subplots`,
 # UltraPlot returns a :class:`~ultraplot.gridspec.SubplotGrid` of subplots. This list-like,
 # array-like object provides some useful features and unifies the behavior of the
-# three possible return types used by `matplotlib.pyplot.subplots`:
+# three possible return types used by :func:`matplotlib.pyplot.subplots`:
 #
 # * :class:`~ultraplot.gridspec.SubplotGrid` behaves like a scalar when it is singleton.
 #   In other words, if you make a single subplot with ``fig, axs = uplt.subplots()``,
@@ -255,7 +260,7 @@
 # :func:`~ultraplot.gridspec.SubplotGrid.panel_axes`,
 # :func:`~ultraplot.gridspec.SubplotGrid.inset_axes`,
 # :func:`~ultraplot.gridspec.SubplotGrid.altx`, and :func:`~ultraplot.gridspec.SubplotGrid.alty`.
-# In the below example, we use `ultraplot.gridspec.SubplotGrid.format` on the grid
+# In the below example, we use :func:`~ultraplot.gridspec.SubplotGrid.format` on the grid
 # returned by :func:`~ultraplot.ui.subplots` to format different subgroups of subplots
 # (:ref:`see below <ug_format>` for more on the format command).
 #
@@ -264,7 +269,7 @@
 #    If you create subplots one-by-one with :func:`~ultraplot.figure.Figure.subplot` or
 #    :func:`~ultraplot.figure.Figure.add_subplot`, a :class:`~ultraplot.gridspec.SubplotGrid`
 #    containing the numbered subplots is available via the
-#    :class:`ultraplot.figure.Figure.subplotgrid` property. As with subplots made
+#    :class:`~ultraplot.figure.Figure.subplotgrid` property. As with subplots made
 #    all-at-once, the subplots in the grid are sorted by :func:`~ultraplot.axes.Axes.number`.
 
 # %%
@@ -294,6 +299,7 @@
 axs[1, :1].format(fc="sky blue")
 axs[-1, -1].format(fc="gray4", grid=False)
 axs[0].plot((state.rand(50, 10) - 0.5).cumsum(axis=0), cycle="Grays_r", lw=2)
+fig.show()
 
 
 # %% [raw] raw_mimetype="text/restructuredtext"
@@ -305,13 +311,13 @@
 # Matplotlib includes `two different interfaces
 # <https://matplotlib.org/stable/api/index.html>`__ for plotting stuff:
 # a python-style object-oriented interface with axes-level commands
-# like :func:`matplotlib.axes.Axes.plot`, and a MATLAB-style :func:`~matplotlib.pyplot` interface
+# like :method:`matplotlib.axes.Axes.plot`, and a MATLAB-style :mod:`~matplotlib.pyplot` interface
 # with global commands like :func:`matplotlib.pyplot.plot` that track the "current" axes.
-# UltraPlot builds upon the python-style interface using the `ultraplot.axes.PlotAxes`
+# UltraPlot builds upon the python-style interface using the `~ultraplot.axes.PlotAxes`
 # class. Since every axes used by UltraPlot is a child of :class:`~ultraplot.axes.PlotAxes`, we
 # are able to add features directly to the axes-level commands rather than relying
 # on a separate library of commands  (note that while some of these features may be
-# accessible via :func:`~matplotlib.pyplot` commands, this is not officially supported).
+# accessible via :mod:`~matplotlib.pyplot` commands, this is not officially supported).
 #
 # For the most part, the features added by :class:`~ultraplot.axes.PlotAxes` represent
 # a *superset* of matplotlib. If you are not interested, you can use the plotting
@@ -353,6 +359,7 @@
     suptitle="Quick plotting demo",
 )
 fig.colorbar(m, loc="b", label="label")
+fig.show()
 
 
 # %% [raw] raw_mimetype="text/restructuredtext"
@@ -364,9 +371,9 @@
 # Matplotlib includes `two different interfaces
 # <https://matplotlib.org/stable/api/index.html>`__ for formatting stuff:
 # a "python-style" object-oriented interface with instance-level commands
-# like `matplotlib.axes.Axes.set_title`, and a "MATLAB-style" interface
+# like :func:`matplotlib.axes.Axes.set_title`, and a "MATLAB-style" interface
 # that tracks current axes and provides global commands like
-# `matplotlib.pyplot.title`.
+# :func:`matplotlib.pyplot.title`.
 #
 # UltraPlot provides the ``format`` command as an
 # alternative "python-style" command for formatting a variety of plot elements.
@@ -380,28 +387,28 @@
 #
 # * Figure settings. These are related to row labels, column labels, and
 #   figure "super" titles -- for example, ``fig.format(suptitle='Super title')``.
-#   See `ultraplot.figure.Figure.format` for details.
+#   See :func:`~ultraplot.figure.Figure.format` for details.
 #
 # * General axes settings. These are related to background patches,
 #   a-b-c labels, and axes titles -- for example, ``ax.format(title='Title')``
-#   See `ultraplot.axes.Axes.format` for details.
+#   See :func:`~ultraplot.axes.Axes.format` for details.
 #
-# * Cartesian axes settings (valid only for `~ultraplot.axes.CartesianAxes`).
+# * Cartesian axes settings (valid only for :class:`~ultraplot.axes.CartesianAxes`).
 #   These are related to *x* and *y* axis ticks, spines, bounds, and labels --
 #   for example, ``ax.format(xlim=(0, 5))`` changes the x axis bounds.
-#   See :func:`ultraplot.axes.CartesianAxes.format` and
+#   See :func:`~ultraplot.axes.CartesianAxes.format` and
 #   :ref:`this section <ug_cartesian>` for details.
 #
 # * Polar axes settings (valid only for :class:`~ultraplot.axes.PolarAxes`).
 #   These are related to azimuthal and radial grid lines, bounds, and labels --
 #   for example, ``ax.format(rlim=(0, 10))`` changes the radial bounds.
-#   See `ultraplot.axes.PolarAxes.format`
+#   See :func:`~ultraplot.axes.PolarAxes.format`
 #   and :ref:`this section <ug_polar>` for details.
 #
-# * Geographic axes settings (valid only for `~ultraplot.axes.GeoAxes`).
+# * Geographic axes settings (valid only for :class:`~ultraplot.axes.GeoAxes`).
 #   These are related to map bounds, meridian and parallel lines and labels,
 #   and geographic features -- for example, ``ax.format(latlim=(0, 90))``
-#   changes the meridional bounds. See `ultraplot.axes.GeoAxes.format`
+#   changes the meridional bounds. See :func:`~ultraplot.axes.GeoAxes.format`
 #   and :ref:`this section <ug_geoformat>` for details.
 #
 # * :func:`~ultraplot.config.rc` settings. Any keyword matching the name
@@ -414,10 +421,10 @@
 #   See :ref:`this section <ug_config>` for more on rc settings.
 #
 # A ``format`` command is available on every figure and axes.
-# `ultraplot.figure.Figure.format` accepts both figure and axes
+# :func:`~ultraplot.figure.Figure.format` accepts both figure and axes
 # settings (applying them to each numbered subplot by default).
-# Similarly, `ultraplot.axes.Axes.format` accepts both axes and figure
-# settings. There is also a `ultraplot.gridspec.SubplotGrid.format`
+# Similarly, :func:`~ultraplot.axes.Axes.format` accepts both axes and figure
+# settings. There is also a :func:`~ultraplot.gridspec.SubplotGrid.format`
 # command that can be used to change settings for a subset of
 # subplots -- for example, ``axs[:2].format(xtickminor=True)``
 # turns on minor ticks for the first two subplots (see
@@ -463,6 +470,7 @@
     xtickminor=False,
     ygridminor=True,
 )
+fig.show()
 
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_rc:
@@ -471,19 +479,19 @@
 # -------------------
 #
 # A dictionary-like object named :func:`~ultraplot.config.rc` is created when you import
-# UltraPlot. :func:`~ultraplot.config.rc` is similar to the matplotlib `~matplotlib.rcParams`
+# UltraPlot. :func:`~ultraplot.config.rc` is similar to the matplotlib :data:`~matplotlib.rcParams`
 # dictionary, but can be used to change both `matplotlib settings
 # <https://matplotlib.org/stable/tutorials/introductory/customizing.html>`__ and
 # :ref:`ultraplot settings <ug_rcUltraPlot>`. The matplotlib-specific settings are
-# stored in :func:`~ultraplot.config.rc_matplotlib` (our name for `matplotlib.rcParams`) and
-# the UltraPlot-specific settings are stored in `~ultraplot.config.rc_UltraPlot`.
+# stored in :func:`~ultraplot.config.rc_matplotlib` (our name for :data:`~matplotlib.rcParams`) and
+# the UltraPlot-specific settings are stored in :class:`~ultraplot.config.rc_ultraplot`.
 # UltraPlot also includes a :rcraw:`style` setting that can be used to
 # switch between `matplotlib stylesheets
 # <https://matplotlib.org/stable/gallery/style_sheets/style_sheets_reference.html>`__.
 # See the :ref:`configuration section <ug_config>` for details.
 #
 # To modify a setting for just one subplot or figure, you can pass it to
-# `ultraplot.axes.Axes.format` or `ultraplot.figure.Figure.format`. To temporarily
+# :func:`~ultraplot.axes.Axes.format` or :func:`~ultraplot.figure.Figure.format`. To temporarily
 # modify setting(s) for a block of code, use :func:`~ultraplot.config.Configurator.context`.
 # To modify setting(s) for the entire python session, just assign it to the
 # :func:`~ultraplot.config.rc` dictionary or use :func:`~ultraplot.config.Configurator.update`.
@@ -530,6 +538,7 @@
     titleloc="r",
     titlecolor="gray7",
 )
+fig.show()
 
 # Reset persistent modifications from head of cell
 uplt.rc.reset()
@@ -554,3 +563,4 @@
 for ax, style in zip(axs, styles):
     ax.format(style=style, xlabel="xlabel", ylabel="ylabel", title=style)
     ax.plot(data, linewidth=3)
+fig.show()