Python Binding Docstring Updates for Stub Generation

doc/source/spelling_wordlist.txt

@@ -461,6 +461,8 @@ connectedness
 const
 constexpr
 contensts
+contextlib
+contextmanager
 ContourOptions
 Contrarty
 conv
@@ -1787,6 +1789,7 @@ MaxX
 maxy
 maxY
 MaxY
+maxz
 MaxZ
 mbtiles
 mbtowc
@@ -1837,6 +1840,7 @@ minX
 miny
 minY
 MinY
+minz
 MinZ
 Mipmaps
 MiraD

swig/include/Operations.i

@@ -992,30 +992,31 @@ def SuggestedWarpOutput(*args):
     Parameters
     ----------
 
-    src: Dataset
+    src : Dataset
         Source dataset
-    transformer: Transformer
+    transformer : Transformer
         The return value of gdal.Transformer(src, None, options)
         (exclusive with below options parameter)
-    options: list[str]
+    options : list[str]
         List of strings that are the transforming options accepted by
         :cpp:func:`GDALCreateGenImgProjTransformer2` (e.g ``DST_SRS``)
         (exclusive with above transformer parameter)
 
     Returns
     -------
-
-    A SuggestedWarpOutputRes class instance with the following members:
-    - width: number of pixels in width of the output dataset
-    - height: number of pixels in height of the output dataset
-    - xmin: minimum value of the georeferenced X coordinates
-    - ymin: maximum value of the georeferenced Y coordinates
-    - xmax: minimum value of the georeferenced X coordinates
-    - ymax: maximum value of the georeferenced Y coordinates
-    - geotransform: affine geotransformation matrix (6 values)
-
-    Example
-    -------
+    SuggestedWarpOutputRes
+        An instance of the SuggestedWarpOutputRes class with the following members:
+
+        - ``width`` (int): Number of pixels in width of the output dataset.
+        - ``height`` (int): Number of pixels in height of the output dataset.
+        - ``xmin`` (float): Minimum value of the georeferenced X coordinates.
+        - ``ymin`` (float): Minimum value of the georeferenced Y coordinates.
+        - ``xmax`` (float): Maximum value of the georeferenced X coordinates.
+        - ``ymax`` (float): Maximum value of the georeferenced Y coordinates.
+        - ``geotransform`` (tuple of 6 floats): Affine geotransformation matrix.
+
+    Examples
+    --------
 
     >>> ds = gdal.Open("byte.tif")
     >>> res = gdal.SuggestedWarpOutput(ds, ["DST_SRS=EPSG:4326"])

swig/include/python/callback.i

@@ -43,7 +43,7 @@ PyProgressProxy( double dfComplete, const char *pszMessage, void *pData )
         psArgs = Py_BuildValue("(dsO)", dfComplete, pszMessage, Py_None );
     else
         psArgs = Py_BuildValue("(dsO)", dfComplete, pszMessage,
-	                       psInfo->psPyCallbackData );
+                           psInfo->psPyCallbackData );
 
     psResult = PyObject_CallObject( psInfo->psPyCallback, psArgs);
     Py_XDECREF(psArgs);

swig/include/python/docs/gdal_algorithm_docs.i

@@ -12,7 +12,7 @@ Close any dataset arguments or outputs of the algorithm.
 
 Returns
 -------
-boolean
+bool
 
 };
 
@@ -25,8 +25,8 @@ Returns
 -------
 Algorithm
 
-Example
--------
+Examples
+--------
 >>> alg = gdal.GetGlobalAlgorithmRegistry().InstantiateAlg("raster")
 >>> alg.ParseCommandLineArguments(["convert" ,"--input", "byte.tif", "--output",  "/tmp/byte.png"])
 True
@@ -47,8 +47,8 @@ Returns
 -------
 AlgorithmArg
 
-Example
--------
+Examples
+--------
 >>> alg = gdal.Algorithm("raster", "polygonize")
 >>> arg = alg.GetArg("connect-diagonal-pixels")
 >>> arg.GetDescription()
@@ -64,8 +64,8 @@ Returns
 -------
 list
 
-Example
--------
+Examples
+--------
 >>> alg = gdal.Algorithm("raster", "convert")
 >>> sorted(alg.GetArgNames())
 ['append', 'config', 'creation-option', ..., 'progress', 'quiet']
@@ -87,8 +87,8 @@ Returns
 -------
 str
 
-Example
--------
+Examples
+--------
 >>> alg = gdal.Algorithm("raster", "convert")
 >>> alg.GetDescription()
 'Convert a raster dataset.'
@@ -103,8 +103,8 @@ Returns
 -------
 str
 
-Example
--------
+Examples
+--------
 >>> alg = gdal.Algorithm("raster", "convert")
 >>> alg.GetHelpFullURL()
 'https://gdal.org/programs/gdal_raster_convert.html'
@@ -125,8 +125,8 @@ Returns
 -------
 str
 
-Example
--------
+Examples
+--------
 >>> gdal.Algorithm("raster", "info").GetName()
 'info'
 
@@ -140,8 +140,8 @@ Returns
 -------
 list or None
 
-Example
--------
+Examples
+--------
 >>> alg = gdal.Algorithm("raster")
 >>> alg.GetSubAlgorithmNames()
 ['as-features', 'aspect', ..., 'update', 'viewshed']
@@ -156,8 +156,8 @@ Returns
 -------
 str
 
-Example
--------
+Examples
+--------
 >>> import json
 >>> import pprint
 >>> usage = json.loads(gdal.Algorithm("vector", "info").GetUsageAsJSON())
@@ -283,8 +283,8 @@ Returns
 -------
 bool
 
-Example
--------
+Examples
+--------
 >>> alg = gdal.Algorithm("raster")
 >>> alg.HasSubAlgorithms()
 True
@@ -302,8 +302,8 @@ Returns
 -------
 Algorithm or None
 
-Example
--------
+Examples
+--------
 >>> alg = gdal.Algorithm("raster")
 >>> alg.InstantiateSubAlgorithm("convert")
 <osgeo.gdal.Algorithm; proxy of <Swig Object of type 'GDALAlgorithmHS *' at ...> >
@@ -325,8 +325,8 @@ Returns
 bool
     Whether the arguments were successfully parsed
 
-Example
--------
+Examples
+--------
 >>> alg = gdal.Algorithm("vector", "info")
 >>> alg.ParseCommandLineArguments(['poly.shp', '--format', 'text'])
 True
@@ -341,7 +341,7 @@ Parameters
 ----------
 args : list
     List of command line arguments
-callback : function
+callback : callable, optional
     Optional progress callback function
 callback_data
     Optional value to be provided as final argument to callback function
@@ -431,8 +431,8 @@ Returns
 -------
 str
 
-Example
--------
+Examples
+--------
 >>> gdal.AlgorithmArgTypeName(gdal.GAAT_REAL)
 'real'
 
@@ -448,7 +448,7 @@ type : int
 
 Returns
 -------
-boolean
+bool
 
 Examples
 --------

swig/include/python/docs/gdal_band_docs.i

@@ -69,7 +69,7 @@ nFlags : int
 
 Returns
 -------
-int:
+int
    :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure.
 
 ";
@@ -80,7 +80,7 @@ Remove the nodata value for this band.
 
 Returns
 -------
-int:
+int
    :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure.
 
 ";
@@ -99,7 +99,7 @@ imag_fill : float, default = 0.0
 
 Returns
 -------
-int:
+int
    :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure.
 
 ";
@@ -273,9 +273,9 @@ include_out_of_range : bool, default=False
     if ``True``, add out-of-range values into the first and last buckets
 approx_ok : bool, default=True
     if ``True``, compute an approximate histogram by using subsampling or overviews
-callback : function, optional
+callback : callable, optional
              A progress callback function
-callback_data: optional
+callback_data : any, optional
              Optional data to be passed to callback function
 
 Returns
@@ -549,7 +549,7 @@ papszCategoryNames : list
 
 Returns
 -------
-int:
+int
    :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure.
 ";
 
@@ -565,7 +565,7 @@ val : int
 
 Returns
 -------
-int:
+int
    :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure.
 ";
 
@@ -580,7 +580,7 @@ arg : ColorTable
 
 Returns
 -------
-int:
+int
    :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure.
 ";
 
@@ -600,7 +600,7 @@ buckets_in : list
 
 Returns
 -------
-int:
+int
    :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure.
 
 See Also
@@ -619,7 +619,7 @@ val : float
 
 Returns
 -------
-int:
+int
    :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure.
 
 See Also
@@ -650,7 +650,7 @@ val : float
 
 Returns
 -------
-int:
+int
    :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure.
 
 See Also
@@ -672,7 +672,7 @@ stdev : float
 
 Returns
 -------
-int:
+int
    :py:const:`CE_None` on apparent success or :py:const:`CE_Failure` on
    failure.  This method cannot detect whether metadata will be properly saved and
    so may return :py:const:`gdal.`CE_None` even if the statistics will never be
@@ -699,7 +699,7 @@ val : str
 
 Returns
 -------
-int:
+int
    :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure.
 ";