Merge pull request #2221 from lgolston/sphinx-edit

Reduce sphinx warnings

docs/doc-requirements.txt

@@ -1,4 +1,4 @@
-sphinx<6
+sphinx
 sphinx-gallery
 beautifulsoup4
 pydata-sphinx-theme

docs/source/_templates/autosummary/class.rst

@@ -0,0 +1,8 @@
+{{ fullname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+    :members:
+    :inherited-members:

docs/source/reference/crs.rst

@@ -1,10 +1,10 @@
 .. _api.crs:
 
-.. currentmodule:: cartopy
-
 Coordinate reference systems (CRS)
 ----------------------------------
 
+.. module:: cartopy.crs
+
 The :class:`cartopy.crs.CRS` class is the very core of cartopy, all coordinate reference systems
 in cartopy have :class:`~cartopy.crs.CRS` as a parent class.
 
@@ -15,19 +15,21 @@ Base CRS's
    :toctree: generated/
    :template: autosummary/class_without_inherited.rst
 
-   crs.CRS
-   crs.Globe
-   crs.Projection
-   crs.Geodetic
-   crs.Geocentric
-   crs.RotatedGeodetic
-   crs.epsg
+   CRS
+   Globe
+   Projection
+   Geodetic
+   Geocentric
+   RotatedGeodetic
+   epsg
 
 .. _api.geodesic:
 
 Geodesic calculations
 ~~~~~~~~~~~~~~~~~~~~~
 
+.. module:: cartopy.geodesic
+
 The :mod:`cartopy.geodesic` module defines the :class:`cartopy.geodesic.Geodesic` class which can interface with the Proj
 geodesic functions. See the `Proj geodesic page`_ for more background
 information.
@@ -37,7 +39,7 @@ information.
 .. autosummary::
    :toctree: generated/
 
-   geodesic.Geodesic
+   Geodesic
 
 List of projections
 ~~~~~~~~~~~~~~~~~~~

docs/source/reference/index.rst

@@ -6,7 +6,7 @@ API reference
 :Release: |version|
 :Date: |today|
 
-.. module:: cartopy
+.. currentmodule:: cartopy
 
 This is a detailed reference manual for functions, modules,
 and objects in cartopy. For initially learning how to use cartopy,

docs/source/reference/io.rst

@@ -1,7 +1,5 @@
 .. _api.io:
 
-.. module:: cartopy.io
-
 Input/output capabilities (cartopy.io)
 --------------------------------------
 
@@ -14,90 +12,101 @@ data formats.
 Shapefiles
 ~~~~~~~~~~
 
-Cartopy provides a basic interface for accessing shapefiles.
+.. module:: cartopy.io.shapereader
+
+:mod:`cartopy.io.shapereader` provides a basic interface for accessing shapefiles.
 
 .. autosummary::
     :toctree: generated/
 
-    shapereader.Reader
-    shapereader.BasicReader
-    shapereader.Record
-    shapereader.natural_earth
-    shapereader.NEShpDownloader
-    shapereader.gshhs
-    shapereader.GSHHSShpDownloader
-
+    Reader
+    BasicReader
+    FionaReader
+    Record
+    FionaRecord
+    natural_earth
+    NEShpDownloader
+    gshhs
+    GSHHSShpDownloader
 
 Image collections
 ~~~~~~~~~~~~~~~~~
 
+.. module:: cartopy.io.img_nest
+
+:mod:`cartopy.io.img_nest` provides an interface for representing images.
+
 .. autosummary::
     :toctree: generated/
 
-    img_nest.Img
-    img_nest.ImageCollection
-    img_nest.NestedImageCollection
-
+    Img
+    ImageCollection
+    NestedImageCollection
 
 Image tiles
 ~~~~~~~~~~~
 
-These classes provide an interface to the respective tile resources to
+.. module:: cartopy.io.img_tiles
+
+Classes in :mod:`cartopy.io.img_tiles` provide an interface to the respective tile resources to
 automatically load the proper tile and resolution depending on the desired domain.
 
 .. autosummary::
     :toctree: generated/
 
-    img_tiles.OSM
-    img_tiles.GoogleTiles
-    img_tiles.GoogleWTS
-    img_tiles.MapQuestOSM
-    img_tiles.MapQuestOpenAerial
-    img_tiles.MapboxStyleTiles
-    img_tiles.MapboxTiles
-    img_tiles.OrdnanceSurvey
-    img_tiles.QuadtreeTiles
-    img_tiles.Stamen
-
+    OSM
+    GoogleTiles
+    GoogleWTS
+    MapQuestOSM
+    MapQuestOpenAerial
+    MapboxStyleTiles
+    MapboxTiles
+    OrdnanceSurvey
+    QuadtreeTiles
+    Stamen
 
 Open Geospatial Consortium (OGC)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-There are several classes to enable interfacing with OGC clients.
+.. module:: cartopy.io.ogc_clients
+
+:mod:`cartopy.io.ogc_clients` contains several classes to enable interfacing with OGC clients.
 
 .. autosummary::
     :toctree: generated/
 
-    ogc_clients.WFSGeometrySource
-    ogc_clients.WMSRasterSource
-    ogc_clients.WMTSRasterSource
-
+    WFSGeometrySource
+    WMSRasterSource
+    WMTSRasterSource
 
 Shuttle Radar Topography Mission (SRTM)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. module:: cartopy.io.srtm
+
 The SRTM data can be accessed through the :mod:`cartopy.io.srtm` module
 using classes and functions defined below.
 
 .. autosummary::
     :toctree: generated/
     :recursive:
 
-    srtm.SRTM1Source
-    srtm.SRTM3Source
-    srtm.SRTMDownloader
-    srtm.read_SRTM
-    srtm.read_SRTM1
-    srtm.read_SRTM3
-    srtm.add_shading
-
+    SRTM1Source
+    SRTM3Source
+    SRTMDownloader
+    read_SRTM
+    read_SRTM1
+    read_SRTM3
+    add_shading
 
 Base classes and functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These are the base classes that new resources can leverage
+These are the base classes in :mod:`cartopy.io` that new resources can leverage
 to implement a new reader or tile client.
 
+.. module:: cartopy.io
+
 .. autosummary::
     :toctree: generated/
 

docs/source/reference/matplotlib.rst

@@ -11,6 +11,8 @@ projections, such as non-rectangular axes and spines.
 Geoaxes
 ~~~~~~~
 
+.. module:: cartopy.mpl.geoaxes
+
 The most primitive extension is the :class:`cartopy.mpl.geoaxes.GeoAxes` class, which
 extends a Matplotlib Axes and adds a `transform` keyword
 argument to many plotting methods to enable geographic projections and boundary wrapping
@@ -20,17 +22,17 @@ to occur on the axes.
     :toctree: generated/
     :template: autosummary/class_without_inherited.rst
 
-    geoaxes.GeoAxes
-    geoaxes.GeoAxesSubplot
-    geoaxes.GeoSpine
-    geoaxes.InterProjectionTransform
-
+    GeoAxes
+    GeoAxesSubplot
+    GeoSpine
+    InterProjectionTransform
 
-.. currentmodule:: cartopy.mpl
 
 Gridlines and ticks
 ~~~~~~~~~~~~~~~~~~~
 
+.. module:: cartopy.mpl.gridliner
+
 Cartopy can produce gridlines and ticks in any projection and add
 them to the current geoaxes projection, providing a way to add detailed
 location information to the plots.
@@ -39,37 +41,54 @@ location information to the plots.
     :toctree: generated/
     :template: autosummary/class_without_inherited.rst
 
-    gridliner.Gridliner
-    ticker.LongitudeFormatter
-    ticker.LatitudeFormatter
-    ticker.LongitudeLocator
-    ticker.LatitudeLocator
+    Gridliner
+
+.. module:: cartopy.mpl.ticker
+
+.. autosummary::
+    :toctree: generated/
+    :template: autosummary/class_without_inherited.rst
+
+    LongitudeFormatter
+    LatitudeFormatter
+    LongitudeLocator
+    LatitudeLocator
 
 Artist extensions
 ~~~~~~~~~~~~~~~~~
 
+.. module:: cartopy.mpl.feature_artist
+
 Features and images can be added to a :class:`cartopy.mpl.geoaxes.GeoAxes` through
 an extension of the Matplotlib Artist interfaces.
 
 .. autosummary::
     :toctree: generated/
     :template: autosummary/class_without_inherited.rst
 
-    feature_artist.FeatureArtist
-    slippy_image_artist.SlippyImageArtist
+    FeatureArtist
+
+.. module:: cartopy.mpl.slippy_image_artist
+
+.. autosummary::
+    :toctree: generated/
+    :template: autosummary/class_without_inherited.rst
+
+    SlippyImageArtist
 
-.. currentmodule:: cartopy.mpl
 
 Additional extensions
 ~~~~~~~~~~~~~~~~~~~~~
 
+.. module:: cartopy.mpl.patch
+
 Extra functionality that is primarily intended for developers. They describe
 some of the capabilities for transforming
 between GEOS, Shapely, and Matplotlib paths.
 
 .. autosummary::
     :toctree: generated/
 
-    patch.geos_to_path
-    patch.path_segments
-    patch.path_to_geos
+    geos_to_path
+    path_segments
+    path_to_geos