From c9d336fc5efad8a61a4376be5bb1f04adf1578c4 Mon Sep 17 00:00:00 2001 From: lgolston <30876419+lgolston@users.noreply.github.com> Date: Tue, 25 Jul 2023 12:31:55 -0500 Subject: [PATCH 1/3] reduce sphinx warnings --- docs/doc-requirements.txt | 2 +- docs/source/_templates/autosummary/class.rst | 9 ++ docs/source/reference/crs.rst | 22 ++--- docs/source/reference/index.rst | 2 +- docs/source/reference/io.rst | 91 +++++++++++--------- docs/source/reference/matplotlib.rst | 53 ++++++++---- docs/source/reference/transformations.rst | 50 +++++++---- docs/source/whatsnew/v0.14.rst | 2 +- docs/source/whatsnew/v0.17.rst | 2 +- examples/miscellanea/animate_surface.py | 2 +- examples/miscellanea/axes_grid_basic.py | 14 +-- examples/scalar_data/wrapping_global.py | 9 +- lib/cartopy/io/shapereader.py | 18 ++-- lib/cartopy/mpl/geoaxes.py | 3 +- 14 files changed, 169 insertions(+), 110 deletions(-) create mode 100644 docs/source/_templates/autosummary/class.rst diff --git a/docs/doc-requirements.txt b/docs/doc-requirements.txt index 7837bb928..c32eda5d0 100644 --- a/docs/doc-requirements.txt +++ b/docs/doc-requirements.txt @@ -1,4 +1,4 @@ -sphinx<6 +sphinx sphinx-gallery beautifulsoup4 pydata-sphinx-theme diff --git a/docs/source/_templates/autosummary/class.rst b/docs/source/_templates/autosummary/class.rst new file mode 100644 index 000000000..51f5d33b1 --- /dev/null +++ b/docs/source/_templates/autosummary/class.rst @@ -0,0 +1,9 @@ +{{ fullname }} +{{ underline }} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :inherited-members: + diff --git a/docs/source/reference/crs.rst b/docs/source/reference/crs.rst index 49aaf06be..21a9d80cd 100644 --- a/docs/source/reference/crs.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst index 973027ecc..061f297d6 100644 --- a/docs/source/reference/index.rst +++ b/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, diff --git a/docs/source/reference/io.rst b/docs/source/reference/io.rst index e895d7edc..1eebec5d7 100644 --- a/docs/source/reference/io.rst +++ b/docs/source/reference/io.rst @@ -1,7 +1,5 @@ .. _api.io: -.. module:: cartopy.io - Input/output capabilities (cartopy.io) -------------------------------------- @@ -14,68 +12,78 @@ 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. @@ -83,21 +91,22 @@ using classes and functions defined below. :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/ diff --git a/docs/source/reference/matplotlib.rst b/docs/source/reference/matplotlib.rst index ab5f5fcbf..d0eb9bd78 100644 --- a/docs/source/reference/matplotlib.rst +++ b/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,15 +41,24 @@ 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. @@ -55,14 +66,22 @@ an extension of the Matplotlib Artist interfaces. :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. @@ -70,6 +89,6 @@ 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 diff --git a/docs/source/reference/transformations.rst b/docs/source/reference/transformations.rst index 286c3f467..e06eeaac1 100644 --- a/docs/source/reference/transformations.rst +++ b/docs/source/reference/transformations.rst @@ -1,7 +1,5 @@ .. _api.transformations: -.. currentmodule:: cartopy - Image and vector transformations -------------------------------- @@ -11,40 +9,56 @@ and reshape data when going from one projection to another. Image transformations ~~~~~~~~~~~~~~~~~~~~~ +.. module:: cartopy.img_transform + +:mod:`cartopy.img_transform` contains: + .. autosummary:: - :toctree: generated/ + :toctree: generated/ - img_transform.mesh_projection - img_transform.regrid - img_transform.warp_array - img_transform.warp_img + mesh_projection + regrid + warp_array + warp_img Vector transformations ~~~~~~~~~~~~~~~~~~~~~~ +.. module:: cartopy.vector_transform + +:mod:`cartopy.vector_transform` contains: + .. autosummary:: - :toctree: generated/ + :toctree: generated/ - vector_transform.vector_scalar_to_grid + vector_scalar_to_grid Longitude wrapping ~~~~~~~~~~~~~~~~~~ +.. module:: cartopy.util + +:mod:`cartopy.util` contains: + .. autosummary:: - :toctree: generated/ + :toctree: generated/ - util.add_cyclic_point - util.add_cyclic + add_cyclic_point + add_cyclic LinearRing/LineString projection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. module:: cartopy.trace + +:mod:`cartopy.trace` contains: + .. autosummary:: - :toctree: generated/ + :toctree: generated/ - trace.project_linear - trace.Interpolator - trace.CartesianInterpolator - trace.SphericalInterpolator - trace.LineAccumulator + project_linear + Interpolator + CartesianInterpolator + SphericalInterpolator + LineAccumulator diff --git a/docs/source/whatsnew/v0.14.rst b/docs/source/whatsnew/v0.14.rst index 6219127ad..4735b026a 100644 --- a/docs/source/whatsnew/v0.14.rst +++ b/docs/source/whatsnew/v0.14.rst @@ -23,7 +23,7 @@ Features * The SRTM3 data source has been changed to the `LP DAAC Data Pool `_. The Data Pool is more consistent, fixing several missing tiles, and the data is void-filled. - Consequently, the :func:`cartopy.srtm.fill_gaps` function has been deprecated + Consequently, the ``cartopy.srtm.fill_gaps`` function has been deprecated as it has no purpose within the STRM context. The SRTM example has also been updated to skip the void-filling step. Additionally, this data source provides SRTM at a higher resolution of diff --git a/docs/source/whatsnew/v0.17.rst b/docs/source/whatsnew/v0.17.rst index eb32ff67b..329819fd9 100644 --- a/docs/source/whatsnew/v0.17.rst +++ b/docs/source/whatsnew/v0.17.rst @@ -38,7 +38,7 @@ Features * Greg Lucas contributed functionality to plot day/night across the globe, which was turned into a map feature by Phil Elson. The shading can be added - to a map with :data:`cartopy.feature.nightshade.Nightshade(datetime)`. For + to a map with :meth:`cartopy.feature.nightshade.Nightshade(datetime) `. For more information, see the :ref:`sphx_glr_gallery_lines_and_polygons_nightshade.py` example. (:pull:`1135`, :pull:`1181`) diff --git a/examples/miscellanea/animate_surface.py b/examples/miscellanea/animate_surface.py index 5f132d406..28a8355a7 100644 --- a/examples/miscellanea/animate_surface.py +++ b/examples/miscellanea/animate_surface.py @@ -3,7 +3,7 @@ --------------------------- This example demonstrates how to animate -gridded data using `pcolormesh()`. +gridded data using `~cartopy.mpl.geoaxes.GeoAxes.pcolormesh()`. """ from matplotlib.animation import FuncAnimation import matplotlib.pyplot as plt diff --git a/examples/miscellanea/axes_grid_basic.py b/examples/miscellanea/axes_grid_basic.py index 5b191afcc..ab89a4ad4 100644 --- a/examples/miscellanea/axes_grid_basic.py +++ b/examples/miscellanea/axes_grid_basic.py @@ -2,12 +2,14 @@ Using Cartopy and AxesGrid toolkit ---------------------------------- -This example demonstrates how to use cartopy `GeoAxes` with -`AxesGrid` from the `mpl_toolkits.axes_grid1`. -The script constructs an `axes_class` kwarg with Plate Carree projection -and passes it to the `AxesGrid` instance. The `AxesGrid` built-in -tick labelling is not used, and instead a standard procedure -of creating grid lines is used. Then some fake data is plotted. +This example demonstrates how to use cartopy `~cartopy.mpl.geoaxes.GeoAxes` +with `~mpl_toolkits.axes_grid1.axes_grid.AxesGrid` from the +:mod:`mpl_toolkits.axes_grid1`. The script constructs an ``axes_class`` kwarg +with Plate Carree projection and passes it to the +`~mpl_toolkits.axes_grid1.axes_grid.AxesGrid` instance. The +`~mpl_toolkits.axes_grid1.axes_grid.AxesGrid` built-in tick labelling +is not used, and instead a standard procedure of creating grid lines is used. +Then some fake data is plotted. """ import matplotlib.pyplot as plt from mpl_toolkits.axes_grid1 import AxesGrid diff --git a/examples/scalar_data/wrapping_global.py b/examples/scalar_data/wrapping_global.py index 2a067b221..1655166ed 100644 --- a/examples/scalar_data/wrapping_global.py +++ b/examples/scalar_data/wrapping_global.py @@ -8,10 +8,11 @@ not plot data between the last and the first longitude. To help with this, the data and longitude/latitude coordinate arrays can be -expanded with a cyclic point to close this gap. The routine `add_cyclic` -repeats the last data column. It can also add the first longitude plus the -cyclic keyword (defaults to 360) to the end of the longitude array so that the -data values at the ending longitudes will be closed to the wrap point. +expanded with a cyclic point to close this gap. The routine +`~cartopy.util.add_cyclic` repeats the last data column. It can also add the +first longitude plus the cyclic keyword (defaults to 360) to the end of the +longitude array so that the data values at the ending longitudes will be closed +to the wrap point. """ import matplotlib.pyplot as plt diff --git a/lib/cartopy/io/shapereader.py b/lib/cartopy/io/shapereader.py index d882d8ba4..b38b68606 100644 --- a/lib/cartopy/io/shapereader.py +++ b/lib/cartopy/io/shapereader.py @@ -125,8 +125,9 @@ class BasicReader: """ Provide an interface for accessing the contents of a shapefile. - The primary methods used on a Reader instance are - :meth:`~Reader.records` and :meth:`~Reader.geometries`. + The primary methods used on a BasicReader instance are + :meth:`~cartopy.io.shapereader.BasicReader.records` and + :meth:`~cartopy.io.shapereader.BasicReader.geometries`. """ @@ -152,7 +153,7 @@ def geometries(self): This interface is useful for accessing the geometries of the shapefile where knowledge of the associated metadata is not necessary. In the case where further metadata is needed use the - :meth:`~Reader.records` + :meth:`~cartopy.io.shapereader.BasicReader.records` interface instead, extracting the geometry from the record with the :meth:`~Record.geometry` method. @@ -179,8 +180,9 @@ class FionaReader: Provides an interface for accessing the contents of a shapefile with the fiona library, which has a much faster reader than pyshp. - The primary methods used on a Reader instance are - :meth:`~Reader.records` and :meth:`~Reader.geometries`. + The primary methods used on a FionaReader instance are + :meth:`~cartopy.io.shapereader.FionaReader.records` and + :meth:`~cartopy.io.shapereader.FionaReader.geometries`. """ @@ -232,9 +234,9 @@ def geometries(self): This interface is useful for accessing the geometries of the shapefile where knowledge of the associated metadata is desired. In the case where further metadata is needed use the - :meth:`~Reader.records` + :meth:`~cartopy.io.shapereader.FionaReader.records` interface instead, extracting the geometry from the record with the - :meth:`~Record.geometry` method. + :meth:`~cartopy.io.shapereader.FionaRecord.geometry` method. """ for item in self._data: @@ -242,7 +244,7 @@ def geometries(self): def records(self): """ - Returns an iterator of :class:`~Record` instances. + Returns an iterator of :class:`~FionaRecord` instances. """ for item in self._data: diff --git a/lib/cartopy/mpl/geoaxes.py b/lib/cartopy/mpl/geoaxes.py index 11f0d3a64..18e38a400 100644 --- a/lib/cartopy/mpl/geoaxes.py +++ b/lib/cartopy/mpl/geoaxes.py @@ -288,6 +288,7 @@ def draw(self, renderer): return ret def set_position(self, position): + """GeoSpine does not support changing its position.""" raise NotImplementedError( 'GeoSpine does not support changing its position.') @@ -434,7 +435,7 @@ def add_image(self, factory, *args, **kwargs): Currently an image "factory" is just an object with an ``image_for_domain`` method. Examples of image factories are :class:`cartopy.io.img_nest.NestedImageCollection` and - :class:`cartopy.io.image_tiles.GoogleTiles`. + :class:`cartopy.io.img_tiles.GoogleTiles`. """ if hasattr(factory, 'image_for_domain'): From 1476a7b0882e5377fcd64ef232c6fda85eeee8ed Mon Sep 17 00:00:00 2001 From: lgolston <30876419+lgolston@users.noreply.github.com> Date: Tue, 25 Jul 2023 13:44:06 -0500 Subject: [PATCH 2/3] fix end of file --- docs/source/_templates/autosummary/class.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/_templates/autosummary/class.rst b/docs/source/_templates/autosummary/class.rst index 51f5d33b1..ed93a2966 100644 --- a/docs/source/_templates/autosummary/class.rst +++ b/docs/source/_templates/autosummary/class.rst @@ -6,4 +6,3 @@ .. autoclass:: {{ objname }} :members: :inherited-members: - From 3032f38d99024986f83b8e838b8e5800c97b3282 Mon Sep 17 00:00:00 2001 From: lgolston <30876419+lgolston@users.noreply.github.com> Date: Tue, 25 Jul 2023 21:00:25 -0500 Subject: [PATCH 3/3] sphinx warning --- lib/cartopy/io/img_nest.py | 11 ++++++----- lib/cartopy/mpl/feature_artist.py | 2 +- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/lib/cartopy/io/img_nest.py b/lib/cartopy/io/img_nest.py index 239d62588..f44dbd54e 100644 --- a/lib/cartopy/io/img_nest.py +++ b/lib/cartopy/io/img_nest.py @@ -80,9 +80,9 @@ def world_files(fname): Determine potential world filename combinations, without checking their existence. - For example, a '*.tif' file may have one of the following - popular conventions for world file extensions '*.tifw', - '*.tfw', '*.TIFW' or '*.TFW'. + For example, a ``'*.tif'`` file may have one of the following + popular conventions for world file extensions ``'*.tifw'``, + ``'*.tfw'``, ``'*.TIFW'`` or ``'*.TFW'``. Given the possible world file extensions, the upper case basename combinations are also generated. For example, the file 'map.tif' @@ -205,7 +205,7 @@ def scan_dir_for_imgs(self, directory, glob_pattern='*.tif', The directory path to search for image files. glob_pattern: optional The image filename glob pattern to search with. - Defaults to '*.tif'. + Defaults to ``'*.tif'``. img_class: optional The class used to construct each image in the Collection. @@ -497,7 +497,8 @@ def from_configuration(cls, name, crs, name_dir_pairs, name_dir_pairs A list of image collection name and directory path pairs. glob_pattern: optional - The image collection filename glob pattern. Defaults to '*.tif'. + The image collection filename glob pattern. Defaults + to ``'*.tif'``. img_class: optional The class of images created in the image collection. diff --git a/lib/cartopy/mpl/feature_artist.py b/lib/cartopy/mpl/feature_artist.py index fea77c4ff..35b331423 100644 --- a/lib/cartopy/mpl/feature_artist.py +++ b/lib/cartopy/mpl/feature_artist.py @@ -133,7 +133,7 @@ def __init__(self, feature, **kwargs): def draw(self, renderer, *args, **kwargs): """ Draw the geometries of the feature that intersect with the extent of - the :class:`cartopy.mpl.GeoAxes` instance to which this + the :class:`cartopy.mpl.geoaxes.GeoAxes` instance to which this object has been added. """