Update geo doc (#129)

* update intersphinx links

Author: cvanelteren

docs/projections.py

@@ -38,21 +38,21 @@
 # ----------
 #
 # To create `polar axes <polar_>`_, pass ``proj='polar'`` to an axes-creation
-# command like `ultraplot.figure.Figure.add_subplot`. Polar axes are represented with the
+# command like :meth:`ultraplot.figure.Figure.add_subplot`. Polar axes are represented with the
 # :class:`~ultraplot.axes.PolarAxes` subclass, which has its own :func:`~ultraplot.axes.PolarAxes.format`
-# command. `ultraplot.axes.PolarAxes.format` facilitates polar-specific modifications
+# command. :meth:`ultraplot.axes.PolarAxes.format` facilitates polar-specific modifications
 # like changing the central radius `r0`, the zero azimuth location `theta0`,
 # and the positive azimuthal direction `thetadir`. It also supports toggling and
 # configuring the "major" and "minor" gridline locations with `grid`, `rlocator`,
 # `thetalocator`, `gridminor`, `rminorlocator`, and `thetaminorlocator` and formatting
 # the gridline labels with `rformatter` and `thetaformatter` (analogous to `xlocator`,
 # `xformatter`, and `xminorlocator` used by :func:`ultraplot.axes.CartesianAxes.format`),
 # and creating "annular" or "sector" plots by changing the radial or azimuthal
-# bounds `rlim` and `thetalim`. Finally, since `ultraplot.axes.PolarAxes.format`
-# calls `ultraplot.axes.Axes.format`, it can be used to add axes titles, a-b-c
+# bounds `rlim` and `thetalim`. Finally, since :meth:`ultraplot.axes.PolarAxes.format`
+# calls :meth:`ultraplot.axes.Axes.format`, it can be used to add axes titles, a-b-c
 # labels, and figure titles.
 #
-# For details, see `ultraplot.axes.PolarAxes.format`.
+# For details, see :meth:`ultraplot.axes.PolarAxes.format`.
 
 # %%
 import ultraplot as uplt
@@ -114,16 +114,16 @@
 # ---------------
 #
 # To create geographic axes, pass ``proj='name'`` to an axes-creation command like
-# `ultraplot.figure.Figure.add_subplot`, where ``name`` is any valid :ref:`PROJ projection
-# name <proj_table>`. Alternatively, you can pass a `cartopy.crs.Projection` or
-# `~mpl_toolkits.basemap.Basemap` instance returned by the :class:`~ultraplot.constructor.Proj`
+# :meth:`ultraplot.figure.Figure.add_subplot`, where ``name`` is any valid :ref:`PROJ projection
+# name <proj_table>`. Alternatively, you can pass a :class:`cartopy.crs.Projection` or
+# :class:`~mpl_toolkits.basemap.Basemap` instance returned by the :class:`~ultraplot.constructor.Proj`
 # :ref:`constructor function <why_constructor>` to `proj` (see below for details). If
 # you want to create your subplots :ref:`all-at-once <ug_subplot>` with e.g.
 # :func:`~ultraplot.ui.subplots` but need different projections for each subplot, you can pass
 # a list or dictionary to the `proj` keyword (e.g., ``proj=('cartesian', 'pcarree')``
 # or ``proj={2: 'pcarree'}`` -- see :func:`~ultraplot.figure.Figure.subplots` for details).
-# Geographic axes are represented with the `~ultraplot.axes.GeoAxes` subclass, which
-# has its own :func:`~ultraplot.axes.GeoAxes.format` command. `ultraplot.axes.GeoAxes.format`
+# Geographic axes are represented with the :class:`~ultraplot.axes.GeoAxes` subclass, which
+# has its own :meth:`~ultraplot.axes.GeoAxes.format` command. :meth:`ultraplot.axes.GeoAxes.format`
 # facilitates :ref:`geographic-specific modifications <ug_geoformat>` like meridional
 # and parallel gridlines and land mass outlines. The syntax is very similar to
 # :func:`ultraplot.axes.CartesianAxes.format`. Note that the `proj` keyword and several of
@@ -151,78 +151,75 @@
 # Geographic backends
 # -------------------
 #
-# The `ultraplot.axes.GeoAxes` class uses either `cartopy`_ or `basemap`_ as "backends"
+# The :class:`ultraplot.axes.GeoAxes` class uses either `cartopy`_ or `basemap`_ as "backends"
 # to :ref:`format the axes <ug_geoformat>` and :ref:`plot stuff <ug_geoplot>` in
 # the axes. A few details:
 #
 # * Cartopy is the default backend. When you request projection names with cartopy
-#   as the backend (or pass a `cartopy.crs.Projection` to the `proj` keyword), the
-#   returned axes is a subclass of `cartopy.mpl.geoaxes.GeoAxes`. Under the hood,
+#   as the backend (or pass a :class:`cartopy.crs.Projection` to the `proj` keyword), the
+#   returned axes is a subclass of :class:`cartopy.mpl.geoaxes.GeoAxes`. Under the hood,
 #   invoking :func:`~ultraplot.axes.GeoAxes.format` with cartopy as the backend changes map
-#   bounds using `~cartopy.mpl.geoaxes.GeoAxes.set_extent`, adds major and minor
-#   gridlines using `~cartopy.mpl.geoaxes.GeoAxes.gridlines`, and adds geographic
-#   features using `~cartopy.mpl.geoaxes.GeoAxes.add_feature`. If you prefer, you can
-#   use the standard `cartopy.mpl.geoaxes.GeoAxes` methods just like you would in
-#   cartopy. If you need to use the underlying `~cartopy.crs.Projection` instance, it
+#   bounds using :meth:`~cartopy.mpl.geoaxes.GeoAxes.set_extent`, adds major and minor
+#   gridlines using :mod:`~cartopy.mpl.geoaxes.GeoAxes.gridlines`, and adds geographic
+#   features using :meth:`~cartopy.mpl.geoaxes.GeoAxes.add_feature`. If you prefer, you can
+#   use the standard :class:`cartopy.mpl.geoaxes.GeoAxes` methods just like you would in
+#   cartopy. If you need to use the underlying :class:`~cartopy.crs.Projection` instance, it
 #   is available via the :func:`~ultraplot.axes.GeoAxes.projection` attribute. If you want
 #   to work with the projection classes directly, they are available in the
 #   top-level namespace (e.g., ``proj=uplt.PlateCarre()`` is allowed).
 #
 # * Basemap is an alternative backend. To use basemap, set :rcraw:`geo.backend` to
 #   ``'basemap'`` or pass ``backend='basemap'`` to the axes-creation command. When
 #   you request a projection name with basemap as the backend (or pass a
-#   `~mpl_toolkits.basemap.Basemap` to the `proj` keyword), the returned axes
+#   :class:`~mpl_toolkits.basemap.Basemap` to the `proj` keyword), the returned axes
 #   redirects the plotting methods plot, scatter, contour, contourf, pcolor,
 #   pcolormesh, quiver, streamplot, and barb to the identically named methods on
-#   the `~mpl_toolkits.basemap.Basemap` instance. This means you can work
+#   the :class:`~mpl_toolkits.basemap.Basemap` instance. This means you can work
 #   with the standard axes plotting methods rather than the basemap methods --
 #   just like cartopy. Under the hood, invoking :func:`~ultraplot.axes.GeoAxes.format`
 #   with basemap as the backend adds major and minor gridlines using
-#   :func:`~mpl_toolkits.basemap.Basemap.drawmeridians` and
-#   :func:`~mpl_toolkits.basemap.Basemap.drawparallels` and adds geographic features
-#   using methods like :func:`~mpl_toolkits.basemap.Basemap.fillcontinents`
-#   and :func:`~mpl_toolkits.basemap.Basemap.drawcoastlines`. If you need to
-#   use the underlying `~mpl_toolkits.basemap.Basemap` instance, it is
-#   available as the :func:`~ultraplot.axes.GeoAxes.projection` attribute.
+#   :meth:`~mpl_toolkits.basemap.Basemap.drawmeridians` and
+#   :meth:`~mpl_toolkits.basemap.Basemap.drawparallels` and adds geographic features
+#   using methods like :meth:`~mpl_toolkits.basemap.Basemap.fillcontinents`
+#   and :meth:`~mpl_toolkits.basemap.Basemap.drawcoastlines`. If you need to
+#   use the underlying :class:`~mpl_toolkits.basemap.Basemap` instance, it is
+#   available as the :attr:`~ultraplot.axes.GeoAxes.projection` attribute.
 #
 # Together, these features let you work with geophysical data without invoking
-# verbose cartopy classes like `~cartopy.crs.LambertAzimuthalEqualArea` or
-# keeping track of separate `~mpl_toolkits.basemap.Basemap` instances. This
+# verbose cartopy classes like :calss:`~cartopy.crs.LambertAzimuthalEqualArea` or
+# keeping track of separate :class:`~mpl_toolkits.basemap.Basemap` instances. This
 # considerably reduces the amount of code needed to make complex geographic
 # plots. In the below examples, we create a variety of plots using both
 # cartopy and basemap as backends.
 #
 # .. important::
 #
 #    * By default, UltraPlot bounds polar cartopy projections like
-#      `~cartopy.crs.NorthPolarStereo` at the equator and gives non-polar cartopy
-#      projections global extent by calling `~cartopy.mpl.geoaxes.GeoAxes.set_global`.
+#      :classs:`~cartopy.crs.NorthPolarStereo` at the equator and gives non-polar cartopy
+#      projections global extent by calling :meth:`~cartopy.mpl.geoaxes.GeoAxes.set_global`.
 #      This is a deviation from cartopy, which determines map boundaries automatically
 #      based on the coordinates of the plotted content. To revert to cartopy's
 #      default behavior, set :rcraw:`geo.extent` to ``'auto`` or pass ``extent='auto'``
 #      to :func:`~ultraplot.axes.GeoAxes.format`.
 #    * By default, UltraPlot gives circular boundaries to polar cartopy and basemap
-#      projections like `~cartopy.crs.NorthPolarStereo` (see `this example
+#      projections like :class:`~cartopy.crs.NorthPolarStereo` (see `this example
 #      <https://scitools.org.uk/cartopy/docs/latest/gallery/lines_and_polygons/always_circular_stereo.html>`__
 #      from the cartopy website). To disable this feature, set :rcraw:`geo.round` to
 #      ``False`` or pass ``round=False` to :func:`~ultraplot.axes.GeoAxes.format`. Please note
 #      that older versions of cartopy cannot add gridlines to maps bounded by circles.
 #    * To make things more consistent, the :class:`~ultraplot.constructor.Proj` constructor
 #      function lets you supply native `PROJ <https://proj.org>`__ keyword names
-#      for the cartopy `~cartopy.crs.Projection` classes (e.g., `lon0` instead
-#      of `central_longitude`) and instantiates `~mpl_toolkits.basemap.Basemap`
+#      for the cartopy :class:`~cartopy.crs.Projection` classes (e.g., `lon0` instead
+#      of `central_longitude`) and instantiates :class:`~mpl_toolkits.basemap.Basemap`
 #      projections with sensible default PROJ parameters rather than raising an error
 #      when they are omitted (e.g., ``lon0=0`` as the default for most projections).
 #
 # .. warning::
-#
-#    The `basemap`_ package is `no longer actively maintained \
-#    <https://matplotlib.org/basemap/users/intro.html#cartopy-new-management-and-eol-announcement>`__
-#    and will not work with matplotlib versions more recent than 3.2.2. We originally
+#    The `basemap`_ package is now being actively maintained again witha short hiatus for a few years. We originally
 #    included basemap support because its gridline labeling was more powerful
-#    than cartopy gridline labeling. However, as cartopy gridline labeling has
-#    significantly improved since version 0.18, UltraPlot may deprecate basemap support
-#    in a future release and fully remove basemap support by version 1.0.0.
+#    than cartopy gridline labeling. While cartopy gridline labeling has
+#    significantly improved since version 0.18, UltraPlot continues to support
+#    both mapping libraries to give users flexibility in their visualization choices.
 
 # %%
 import ultraplot as uplt
@@ -258,19 +255,19 @@
 # -----------------------
 #
 # In UltraPlot, plotting with `~ultraplot.axes.GeoAxes` is just like plotting
-# with `~ultraplot.axes.CartesianAxes`. UltraPlot makes longitude-latitude
+# with :class:`~ultraplot.axes.CartesianAxes`. UltraPlot makes longitude-latitude
 # (i.e., Plate Carrée) coordinates the *default* coordinate system for all plotting
 # commands by internally passing ``transform=ccrs.PlateCarree()`` to cartopy commands
 # and ``latlon=True`` to basemap commands. And again, when `basemap`_ is the backend,
 # plotting is done "cartopy-style" by calling methods from the `ultraplot.axes.GeoAxes`
-# instance rather than the `~mpl_toolkits.basemap.Basemap` instance.
+# instance rather than the :class:`~mpl_toolkits.basemap.Basemap` instance.
 #
 # To ensure that a 2D :class:`~ultraplot.axes.PlotAxes` command like
 # :func:`~ultraplot.axes.PlotAxes.contour` or :func:`~ultraplot.axes.PlotAxes.pcolor`
 # fills the entire globe, simply pass ``globe=True`` to the command.
 # This interpolates the data to the North and South poles and across the longitude
 # seam before plotting. This is a convenient and succinct alternative to cartopy's
-# `~cartopy.util.add_cyclic_point` and basemap's :func:`~mpl_toolkits.basemap.addcyclic`.
+# :meth:`~cartopy.util.add_cyclic_point` and basemap's :meth:`~mpl_toolkits.basemap.addcyclic`.
 #
 # To draw content above or underneath a given geographic feature, simply change
 # the `zorder <https://matplotlib.org/3.1.1/gallery/misc/zorder_demo.html>`__
@@ -329,7 +326,7 @@
 # latitude gridline locations using the `grid`, `lonlocator`, `latlocator`, `gridminor`,
 # `lonminorlocator`, and `latminorlocator` keys, and configure gridline label formatting
 # with `lonformatter` and `latformatter` (analogous to `xlocator`, `xminorlocator`,
-# and `xformatter` used by :func:`ultraplot.axes.CartesianAxes.format`). By default, inline
+# and `xformatter` used by :meth:`ultraplot.axes.CartesianAxes.format`). By default, inline
 # cartopy labels and cartopy label rotation are turned off, but inline labels can
 # be turned on using ``loninline=True``, ``latinline=True``, or ``inlinelabels=True``
 # or by setting :rcraw:`grid.inlinelabels` to ``True``, and label rotation can be
@@ -342,11 +339,11 @@
 # latitude bound for circular polar projections using `boundinglat`, and toggle and
 # configure geographic features like land masses, coastlines, and administrative
 # borders using :ref:`settings <rc_UltraPlot>` like `land`, `landcolor`, `coast`,
-# `coastcolor`, and `coastlinewidth`. Finally, since `ultraplot.axes.GeoAxes.format`
-# calls `ultraplot.axes.Axes.format`, it can be used to add axes titles, a-b-c labels,
+# `coastcolor`, and `coastlinewidth`. Finally, since :meth:`ultraplot.axes.GeoAxes.format`
+# calls :meth:`ultraplot.axes.Axes.format`, it can be used to add axes titles, a-b-c labels,
 # and figure titles, just like :func:`ultraplot.axes.CartesianAxes.format`. UltraPlot also adds the ability to add tick marks for longitude and latitude using the keywords `lontick` and `lattick` for rectilinear projections only. This can enhance contrast and readability under some conditions, e.g. when overlaying contours.
 #
-# For details, see the `ultraplot.axes.GeoAxes.format` documentation.
+# For details, see the :meth:`ultraplot.axes.GeoAxes.format` documentation.
 
 # %%
 import ultraplot as uplt
@@ -422,14 +419,14 @@
 # ------------------------
 #
 # To zoom into cartopy projections, use
-# `~cartopy.mpl.geoaxes.GeoAxes.set_extent` or pass `lonlim`,
-# `latlim`, or `boundinglat` to :func:`~ultraplot.axes.GeoAxes.format`. The `boundinglat`
+# :meth:`~cartopy.mpl.geoaxes.GeoAxes.set_extent` or pass `lonlim`,
+# `latlim`, or `boundinglat` to :meth:`~ultraplot.axes.GeoAxes.format`. The `boundinglat`
 # keyword controls the circular latitude boundary for North Polar and
 # South Polar Stereographic, Azimuthal Equidistant, Lambert Azimuthal
 # Equal-Area, and Gnomonic projections. By default, UltraPlot tries to use the
 # degree-minute-second cartopy locators and formatters made available in cartopy
 # 0.18. You can switch from minute-second subintervals to traditional decimal
-# subintervals by passing ``dms=False`` to :func:`~ultraplot.axes.GeoAxes.format`
+# subintervals by passing ``dms=False`` to :meth:`~ultraplot.axes.GeoAxes.format`
 # or by setting :rcraw:`grid.dmslabels` to ``False``.
 #
 # To zoom into basemap projections, pass any of the `boundinglat`,
@@ -521,8 +518,8 @@
 # and ``'kav7'``), as well as North and South polar versions of the Azimuthal
 # Equidistant, Lambert Azimuthal Equal-Area, and Gnomonic projections (i.e.,
 # ``'npaeqd'``, ``'spaeqd'``, ``'nplaea'``, ``'splaea'``, ``'npgnom'``, and
-# ``'spgnom'``), modeled after cartopy's existing `~cartopy.crs.NorthPolarStereo`
-# and `~cartopy.crs.SouthPolarStereo` projections.
+# ``'spgnom'``), modeled after cartopy's existing :class:`~cartopy.crs.NorthPolarStereo`
+# and :class:`~cartopy.crs.SouthPolarStereo` projections.
 
 # %%
 import ultraplot as uplt