Show module docstring and combine from rst

SciTools · Mar 18, 2024 · 3c061d9 · 3c061d9
1 parent 75ec0fa
commit 3c061d9
Show file tree

Hide file tree

Showing 21 changed files with 64 additions and 97 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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,23 +22,18 @@ 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/
     :template: autosummary/class_without_inherited.rst
 
     Gridliner
 
-.. module:: cartopy.mpl.ticker
+.. automodule:: cartopy.mpl.ticker
 
 .. autosummary::
     :toctree: generated/
@@ -57,33 +47,26 @@ 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/
     :template: autosummary/class_without_inherited.rst
 
     FeatureArtist
 
-.. module:: cartopy.mpl.slippy_image_artist
+.. automodule:: cartopy.mpl.slippy_image_artist
 
 .. autosummary::
     :toctree: generated/
     :template: autosummary/class_without_inherited.rst
 
     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
@@ -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
@@ -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
@@ -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
@@ -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 <https://proj.org/geodesic.html>`_
+for more background information.
 
 """
 import numpy as np

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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>`_
+See also `Shapely Geometric Objects
+<https://shapely.readthedocs.io/en/latest/manual.html#geometric-objects>`_
 and `Matplotlib Path API <https://matplotlib.org/stable/api/path_api.html>`_.
 
-.. 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
@@ -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
@@ -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.