From 3c061d92aef625223f931638d265d7fd7bc8e43b Mon Sep 17 00:00:00 2001 From: lgolston <30876419+lgolston@users.noreply.github.com> Date: Mon, 18 Mar 2024 00:02:13 -0500 Subject: [PATCH] Show module docstring and combine from rst --- docs/source/reference/crs.rst | 13 ++------- docs/source/reference/feature.rst | 7 +---- docs/source/reference/io.rst | 32 +++++++--------------- docs/source/reference/matplotlib.rst | 33 ++++++----------------- docs/source/reference/transformations.rst | 16 +++-------- lib/cartopy/crs.py | 4 ++- lib/cartopy/feature/__init__.py | 6 +++-- lib/cartopy/geodesic.py | 3 ++- lib/cartopy/img_transform.py | 3 +-- lib/cartopy/io/img_nest.py | 4 +++ lib/cartopy/io/img_tiles.py | 3 ++- lib/cartopy/io/shapereader.py | 3 ++- lib/cartopy/io/srtm.py | 3 +++ lib/cartopy/mpl/feature_artist.py | 2 +- lib/cartopy/mpl/geoaxes.py | 4 ++- lib/cartopy/mpl/gridliner.py | 6 +++++ lib/cartopy/mpl/patch.py | 9 +++---- lib/cartopy/mpl/ticker.py | 2 +- lib/cartopy/trace.pyx | 2 +- lib/cartopy/util.py | 3 +-- lib/cartopy/vector_transform.py | 3 +-- 21 files changed, 64 insertions(+), 97 deletions(-) diff --git a/docs/source/reference/crs.rst b/docs/source/reference/crs.rst index 21a9d80cd..07ecdad10 100644 --- a/docs/source/reference/crs.rst +++ b/docs/source/reference/crs.rst @@ -3,10 +3,7 @@ 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. +.. automodule:: cartopy.crs Base CRS's ~~~~~~~~~~ @@ -28,13 +25,7 @@ Base CRS's 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. - -.. _Proj geodesic page: https://proj.org/geodesic.html +.. automodule:: cartopy.geodesic .. autosummary:: :toctree: generated/ diff --git a/docs/source/reference/feature.rst b/docs/source/reference/feature.rst index 7ce942e96..c8af1b80e 100644 --- a/docs/source/reference/feature.rst +++ b/docs/source/reference/feature.rst @@ -3,12 +3,7 @@ Feature interface (cartopy.feature) ----------------------------------- -.. module:: cartopy.feature - -The feature interface can be used and extended to add various "features" -to geoaxes, such as Shapely objects and Natural Earth Imagery. The default -zorder for Cartopy features is 1.5, which puts them above images and patches, -but below lines and text. +.. automodule:: cartopy.feature Feature attributes ~~~~~~~~~~~~~~~~~~ diff --git a/docs/source/reference/io.rst b/docs/source/reference/io.rst index 72b69b756..faf593858 100644 --- a/docs/source/reference/io.rst +++ b/docs/source/reference/io.rst @@ -9,12 +9,10 @@ data formats. .. _api.io.shapereader: -Shapefiles -~~~~~~~~~~ - -.. module:: cartopy.io.shapereader +Shapereader +~~~~~~~~~~~ -:mod:`cartopy.io.shapereader` provides a basic interface for accessing shapefiles. +.. automodule:: cartopy.io.shapereader .. autosummary:: :toctree: generated/ @@ -32,9 +30,7 @@ Shapefiles Image collections ~~~~~~~~~~~~~~~~~ -.. module:: cartopy.io.img_nest - -:mod:`cartopy.io.img_nest` provides an interface for representing images. +.. automodule:: cartopy.io.img_nest .. autosummary:: :toctree: generated/ @@ -46,10 +42,7 @@ Image collections Image tiles ~~~~~~~~~~~ -.. 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. +.. automodule:: cartopy.io.img_tiles .. autosummary:: :toctree: generated/ @@ -66,12 +59,10 @@ automatically load the proper tile and resolution depending on the desired domai StadiaMapsTiles Stamen -Open Geospatial Consortium (OGC) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. module:: cartopy.io.ogc_clients +Open Geospatial Consortium (OGC) Clients +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:mod:`cartopy.io.ogc_clients` contains several classes to enable interfacing with OGC clients. +.. automodule:: cartopy.io.ogc_clients .. autosummary:: :toctree: generated/ @@ -83,10 +74,7 @@ Open Geospatial Consortium (OGC) 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. +.. automodule:: cartopy.io.srtm .. autosummary:: :toctree: generated/ @@ -106,7 +94,7 @@ Base classes and functions 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 +.. automodule:: cartopy.io .. autosummary:: :toctree: generated/ diff --git a/docs/source/reference/matplotlib.rst b/docs/source/reference/matplotlib.rst index 82cf6ee8e..dba9f9ae1 100644 --- a/docs/source/reference/matplotlib.rst +++ b/docs/source/reference/matplotlib.rst @@ -6,17 +6,12 @@ Matplotlib interface (cartopy.mpl) Cartopy extends some Matplotlib capabilities to handle geographic projections, such as non-rectangular axes and spines. -.. module:: cartopy.mpl +.. automodule:: cartopy.mpl 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 -to occur on the axes. +.. automodule:: cartopy.mpl.geoaxes .. autosummary:: :toctree: generated/ @@ -27,15 +22,10 @@ to occur on the axes. GeoSpine InterProjectionTransform - 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. +.. automodule:: cartopy.mpl.gridliner .. autosummary:: :toctree: generated/ @@ -43,7 +33,7 @@ location information to the plots. Gridliner -.. module:: cartopy.mpl.ticker +.. automodule:: cartopy.mpl.ticker .. autosummary:: :toctree: generated/ @@ -57,10 +47,7 @@ location information to the plots. 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. +.. automodule:: cartopy.mpl.feature_artist .. autosummary:: :toctree: generated/ @@ -68,7 +55,7 @@ an extension of the Matplotlib Artist interfaces. FeatureArtist -.. module:: cartopy.mpl.slippy_image_artist +.. automodule:: cartopy.mpl.slippy_image_artist .. autosummary:: :toctree: generated/ @@ -76,14 +63,10 @@ an extension of the Matplotlib Artist interfaces. SlippyImageArtist - -Additional extensions +Patch ~~~~~~~~~~~~~~~~~~~~~ -.. module:: cartopy.mpl.patch - -Extra functionality that is primarily intended for developers. They describe -some of the capabilities for transforming between Shapely, and Matplotlib paths. +.. automodule:: cartopy.mpl.patch .. autosummary:: :toctree: generated/ diff --git a/docs/source/reference/transformations.rst b/docs/source/reference/transformations.rst index e06eeaac1..38e0b81ca 100644 --- a/docs/source/reference/transformations.rst +++ b/docs/source/reference/transformations.rst @@ -9,9 +9,7 @@ and reshape data when going from one projection to another. Image transformations ~~~~~~~~~~~~~~~~~~~~~ -.. module:: cartopy.img_transform - -:mod:`cartopy.img_transform` contains: +.. automodule:: cartopy.img_transform .. autosummary:: :toctree: generated/ @@ -24,9 +22,7 @@ Image transformations Vector transformations ~~~~~~~~~~~~~~~~~~~~~~ -.. module:: cartopy.vector_transform - -:mod:`cartopy.vector_transform` contains: +.. automodule:: cartopy.vector_transform .. autosummary:: :toctree: generated/ @@ -36,9 +32,7 @@ Vector transformations Longitude wrapping ~~~~~~~~~~~~~~~~~~ -.. module:: cartopy.util - -:mod:`cartopy.util` contains: +.. automodule:: cartopy.util .. autosummary:: :toctree: generated/ @@ -50,9 +44,7 @@ Longitude wrapping LinearRing/LineString projection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. module:: cartopy.trace - -:mod:`cartopy.trace` contains: +.. automodule:: cartopy.trace .. autosummary:: :toctree: generated/ diff --git a/lib/cartopy/crs.py b/lib/cartopy/crs.py index 2c707bf74..f25a60889 100644 --- a/lib/cartopy/crs.py +++ b/lib/cartopy/crs.py @@ -125,7 +125,9 @@ def to_proj4_params(self): class CRS(_CRS): """ - Define a Coordinate Reference System using proj. + Define a Coordinate Reference System using proj. 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. """ #: Whether this projection can handle ellipses. diff --git a/lib/cartopy/feature/__init__.py b/lib/cartopy/feature/__init__.py index 295921746..e7b6559fe 100644 --- a/lib/cartopy/feature/__init__.py +++ b/lib/cartopy/feature/__init__.py @@ -4,8 +4,10 @@ # See LICENSE in the root of the repository for full licensing details. """ -This module defines :class:`Feature` instances, for use with -ax.add_feature(). +This module defines a :class:`Feature` interface, which can be used and extended to +add various "features" to geoaxes using ax.add_feature(), such as Shapely objects and +Natural Earth Imagery. The default zorder for Cartopy features is 1.5, which puts them +above images and patches, but below lines and text. """ diff --git a/lib/cartopy/geodesic.py b/lib/cartopy/geodesic.py index b6c21a24d..0cd8c17e4 100644 --- a/lib/cartopy/geodesic.py +++ b/lib/cartopy/geodesic.py @@ -7,7 +7,8 @@ """ This module defines the Geodesic class which can interface with the Proj -geodesic functions. +geodesic functions. See the `Proj geodesic page `_ +for more background information. """ import numpy as np diff --git a/lib/cartopy/img_transform.py b/lib/cartopy/img_transform.py index 575011a36..9bcd719ad 100644 --- a/lib/cartopy/img_transform.py +++ b/lib/cartopy/img_transform.py @@ -3,8 +3,7 @@ # This file is part of Cartopy and is released under the BSD 3-clause license. # See LICENSE in the root of the repository for full licensing details. """ -This module contains generic functionality to support Cartopy image -transformations. +Generic functionality to support Cartopy image transformations. """ diff --git a/lib/cartopy/io/img_nest.py b/lib/cartopy/io/img_nest.py index 8b2304567..7c07163e9 100644 --- a/lib/cartopy/io/img_nest.py +++ b/lib/cartopy/io/img_nest.py @@ -3,6 +3,10 @@ # This file is part of Cartopy and is released under the BSD 3-clause license. # See LICENSE in the root of the repository for full licensing details. +""" +Provides an interface for representing images. + +""" import collections from pathlib import Path diff --git a/lib/cartopy/io/img_tiles.py b/lib/cartopy/io/img_tiles.py index f96a17f42..a9e92af38 100644 --- a/lib/cartopy/io/img_tiles.py +++ b/lib/cartopy/io/img_tiles.py @@ -4,7 +4,8 @@ # See LICENSE in the root of the repository for full licensing details. """ -Implements image tile identification and fetching from various sources. +Implements image tile identification and fetching from various sources, +automatically loading the proper tile and resolution depending on the desired domain. The Matplotlib interface can make use of tile objects (defined below) via the diff --git a/lib/cartopy/io/shapereader.py b/lib/cartopy/io/shapereader.py index b74648019..344465b26 100644 --- a/lib/cartopy/io/shapereader.py +++ b/lib/cartopy/io/shapereader.py @@ -4,7 +4,8 @@ # See LICENSE in the root of the repository for full licensing details. """ -Combine the shapefile access of pyshp with the +This module provides a basic interface for accessing shapefiles. +Combine the shapefile access of pyshp or fiona with the geometry representation of shapely: >>> import cartopy.io.shapereader as shapereader diff --git a/lib/cartopy/io/srtm.py b/lib/cartopy/io/srtm.py index a7c9b9cbe..11d8fe9fc 100644 --- a/lib/cartopy/io/srtm.py +++ b/lib/cartopy/io/srtm.py @@ -11,6 +11,9 @@ - Wikipedia (August 2012) +The SRTM data can be accessed through the :mod:`cartopy.io.srtm` module +using classes and functions defined below. + """ import io diff --git a/lib/cartopy/mpl/feature_artist.py b/lib/cartopy/mpl/feature_artist.py index 6d4f42459..7570be448 100644 --- a/lib/cartopy/mpl/feature_artist.py +++ b/lib/cartopy/mpl/feature_artist.py @@ -5,7 +5,7 @@ """ This module defines the :class:`FeatureArtist` class, for drawing -:class:`Feature` instances with matplotlib. +:class:`Feature` instances through an extension of the Matplotlib Artist interfaces. """ diff --git a/lib/cartopy/mpl/geoaxes.py b/lib/cartopy/mpl/geoaxes.py index 3074f8c97..005dd8e8e 100644 --- a/lib/cartopy/mpl/geoaxes.py +++ b/lib/cartopy/mpl/geoaxes.py @@ -4,7 +4,9 @@ # See LICENSE in the root of the repository for full licensing details. """ -This module defines the :class:`GeoAxes` class, for use with matplotlib. +This module defines the :class:`cartopy.mpl.geoaxes.GeoAxes` class, an extension of +matplotlib which adds a `transform` keyword argument to many plotting methods to enable +geographic projections and boundary wrapping to occur on the axes. When a Matplotlib figure contains a GeoAxes the plotting commands can transform plot results from source coordinates to the GeoAxes' target projection. diff --git a/lib/cartopy/mpl/gridliner.py b/lib/cartopy/mpl/gridliner.py index ba9ddb162..c750a7543 100644 --- a/lib/cartopy/mpl/gridliner.py +++ b/lib/cartopy/mpl/gridliner.py @@ -2,6 +2,12 @@ # # This file is part of Cartopy and is released under the BSD 3-clause license. # See LICENSE in the root of the repository for full licensing details. +""" +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. + +""" import itertools import operator diff --git a/lib/cartopy/mpl/patch.py b/lib/cartopy/mpl/patch.py index 9c7749d7f..49b841bce 100644 --- a/lib/cartopy/mpl/patch.py +++ b/lib/cartopy/mpl/patch.py @@ -3,14 +3,13 @@ # This file is part of Cartopy and is released under the BSD 3-clause license. # See LICENSE in the root of the repository for full licensing details. """ -Provide shapely geometry <-> matplotlib path support. +Extra functionality that is primarily intended for developers, providing support for +transforming between Shapely geometries and Matplotlib paths. -See also `Shapely Geometric Objects `_ +See also `Shapely Geometric Objects +`_ and `Matplotlib Path API `_. -.. see_also_shapely: - https://shapely.readthedocs.io/en/latest/manual.html#geometric-objects - """ from matplotlib.path import Path diff --git a/lib/cartopy/mpl/ticker.py b/lib/cartopy/mpl/ticker.py index d261c3ab9..cdc2fa4a1 100644 --- a/lib/cartopy/mpl/ticker.py +++ b/lib/cartopy/mpl/ticker.py @@ -2,7 +2,7 @@ # # This file is part of Cartopy and is released under the BSD 3-clause license. # See LICENSE in the root of the repository for full licensing details. -"""This module contains tools for handling tick marks in cartopy.""" +"""Tools for handling tick marks in cartopy.""" import matplotlib as mpl from matplotlib.ticker import Formatter, MaxNLocator diff --git a/lib/cartopy/trace.pyx b/lib/cartopy/trace.pyx index 082f7b293..9d386324a 100644 --- a/lib/cartopy/trace.pyx +++ b/lib/cartopy/trace.pyx @@ -6,7 +6,7 @@ # cython: embedsignature=True """ -This module pulls together proj, GEOS and ``_crs.pyx`` to implement a function +Trace pulls together proj, GEOS and ``_crs.pyx`` to implement a function to project a `~shapely.geometry.LinearRing` / `~shapely.geometry.LineString`. In general, this should never be called manually, instead leaving the processing to be done by the :class:`cartopy.crs.Projection` subclasses. diff --git a/lib/cartopy/util.py b/lib/cartopy/util.py index 1022ce18e..28142de35 100644 --- a/lib/cartopy/util.py +++ b/lib/cartopy/util.py @@ -3,8 +3,7 @@ # This file is part of Cartopy and is released under the BSD 3-clause license. # See LICENSE in the root of the repository for full licensing details. """ -This module contains utilities that are useful in conjunction with -cartopy. +Utilities that are useful in conjunction with cartopy. """ import numpy as np diff --git a/lib/cartopy/vector_transform.py b/lib/cartopy/vector_transform.py index 25dbe9e21..b52212a58 100644 --- a/lib/cartopy/vector_transform.py +++ b/lib/cartopy/vector_transform.py @@ -3,8 +3,7 @@ # This file is part of Cartopy and is released under the BSD 3-clause license. # See LICENSE in the root of the repository for full licensing details. """ -This module contains generic functionality to support Cartopy vector -transforms. +Generic functionality to support Cartopy vector transforms. """