Merge pull request #347 from davemfish/bugfix/DOCS-346-toc

DOCS: cleanup TOC and various docstring format issues

.readthedocs.yml

@@ -10,8 +10,10 @@ sphinx:
 conda:
     environment: docs/environment-rtd.yml
 
-python:
-    version: 3.8
-    install:
-        - method: setuptools
-          path: .
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "mambaforge-22.9"
+  jobs:
+    post_install:
+      - pip install .

docs/source/_static/custom.css

@@ -0,0 +1,3 @@
+.wy-menu-vertical li.toctree-l3, .wy-menu-vertical li.toctree-l4 {
+	font-size: 1.0em;
+}

docs/source/conf.py

@@ -58,6 +58,7 @@
 html_static_path = ['_static']
 html_logo = os.path.join(os.path.dirname(__file__), '_static',
                          'pygeoprocessing_logo.jpg')
+html_css_files = ['custom.css']
 
 
 # -- Extension configuration -------------------------------------------------

docs/source/index.rst

@@ -40,9 +40,8 @@ Getting Started
 .. toctree::
    :maxdepth: 1
    :caption: API Reference
-   :glob:
 
-   api/*
+   api/pygeoprocessing.rst
 
 
 Indices and tables

src/pygeoprocessing/geoprocessing.py

@@ -156,6 +156,7 @@ class TimedLoggingAdapter(logging.LoggerAdapter):
     This object is helpful for creating consistency in logging callbacks and is
     derived from the python stdlib ``logging.LoggerAdapter``.
     """
+
     def __init__(self, interval_s=_LOGGING_PERIOD):
         """Initialize the timed logging adapter.
 
@@ -1571,12 +1572,12 @@ def zonal_statistics(
     feature polygon. If ``ignore_nodata`` is false, nodata pixels are considered
     valid when calculating the statistics:
 
-    'min': minimum valid pixel value
-    'max': maximum valid pixel value
-    'sum': sum of valid pixel values
-    'count': number of valid pixels
-    'nodata_count': number of nodata pixels
-    'value_counts': number of pixels having each unique value
+    - 'min': minimum valid pixel value
+    - 'max': maximum valid pixel value
+    - 'sum': sum of valid pixel values
+    - 'count': number of valid pixels
+    - 'nodata_count': number of nodata pixels
+    - 'value_counts': number of pixels having each unique value
 
     Note:
         There may be some degenerate cases where the bounding box vs. actual
@@ -2395,16 +2396,17 @@ def warp_raster(
         gdal_warp_options=None, working_dir=None, use_overview_level=-1,
         raster_driver_creation_tuple=DEFAULT_GTIFF_CREATION_TUPLE_OPTIONS,
         osr_axis_mapping_strategy=DEFAULT_OSR_AXIS_MAPPING_STRATEGY):
-    f"""Resize/resample raster to desired pixel size, bbox and projection.
+    """Resize/resample raster to desired pixel size, bbox and projection.
 
     Args:
         base_raster_path (string): path to base raster.
         target_pixel_size (list/tuple): a two element sequence indicating
             the x and y pixel size in projected units.
         target_raster_path (string): the location of the resized and
             resampled raster.
-        resample_method (string): the resampling technique, one of
-            ``{_GDAL_WARP_ALGOS_FOR_HUMAN_EYES}``
+        resample_method (string): the resampling technique, one of,
+            'rms | mode | sum | q1 | near | q3 | average | cubicspline |
+            bilinear | max | med | min | cubic | lanczos'
         target_bb (sequence): if None, target bounding box is the same as the
             source bounding box.  Otherwise it's a sequence of float
             describing target bounding box in target coordinate system as
@@ -3061,11 +3063,10 @@ def convolve_2d(
             bounds of the raster are 0s. If set to false this tends to "pull"
             the signal away from nodata holes or raster edges. Set this value
             to ``True`` to avoid distortions signal values near edges for
-            large integrating kernels.
-                It can be useful to set this value to ``True`` to fill
-            nodata holes through distance weighted averaging. In this case
-            ``mask_nodata`` must be set to ``False`` so the result does not
-            mask out these areas which are filled in. When using this
+            large integrating kernels. It can be useful to set this value to
+            ``True`` to fill nodata holes through distance weighted averaging.
+            In this case ``mask_nodata`` must be set to ``False`` so the result
+            does not mask out these areas which are filled in. When using this
             technique be careful of cases where the kernel does not extend
             over any areas except nodata holes, in this case the resulting
             values in these areas will be nonsensical numbers, perhaps
@@ -4189,15 +4190,16 @@ def stitch_rasters(
         overlap_algorithm='etch',
         area_weight_m2_to_wgs84=False,
         osr_axis_mapping_strategy=DEFAULT_OSR_AXIS_MAPPING_STRATEGY):
-    f"""Stitch the raster in the base list into the existing target.
+    """Stitch the raster in the base list into the existing target.
 
     Args:
         base_raster_path_band_list (sequence): sequence of raster path/band
             tuples to stitch into target.
         resample_method_list (sequence): a sequence of resampling methods
             which one to one map each path in ``base_raster_path_band_list``
-            during resizing.  Each element must be one of
-            ``{_GDAL_WARP_ALGOS_FOR_HUMAN_EYES}``
+            during resizing.  Each element must be one of,
+            'rms | mode | sum | q1 | near | q3 | average | cubicspline |
+            bilinear | max | med | min | cubic | lanczos'
         target_stitch_raster_path_band (tuple): raster path/band tuple to an
             existing raster, values in ``base_raster_path_band_list`` will
             be stitched into this raster/band in the order they are in the
@@ -4213,14 +4215,15 @@ def stitch_rasters(
         overlap_algorithm (str): this value indicates which algorithm to use
             when a raster is stitched on non-nodata values in the target
             stitch raster. It can be one of the following:
-                'etch': write a value to the target raster only if the target
-                    raster pixel is nodata. If the target pixel is non-nodata
-                    ignore any additional values to write on that pixel.
-                'replace': write a value to the target raster irrespective
-                    of the value of the target raster
-                'add': add the value to be written to the target raster to
-                    any existing value that is there. If the existing value
-                    is nodata, treat it as 0.0.
+
+            - 'etch': write a value to the target raster only if the target
+              raster pixel is nodata. If the target pixel is non-nodata
+              ignore any additional values to write on that pixel.
+            - 'replace': write a value to the target raster irrespective
+              of the value of the target raster
+            - 'add': add the value to be written to the target raster to
+              any existing value that is there. If the existing value
+              is nodata, treat it as 0.0.
         area_weight_m2_to_wgs84 (bool): If ``True`` the stitched raster will
             be converted to a per-area value before reprojection to wgs84,
             then multiplied by the m^2 area per pixel in the wgs84 coordinate
@@ -4486,7 +4489,7 @@ def _mult_op(base_array, base_nodata, scale, datatype):
 def build_overviews(
         raster_path, internal=False, resample_method='near',
         overwrite=False, levels='auto'):
-    f"""Build overviews for a raster dataset.
+    """Build overviews for a raster dataset.
 
     Args:
         raster_path (str): A path to a raster on disk for which overviews
@@ -4495,8 +4498,9 @@ def build_overviews(
             overviews. In GeoTiffs, this builds internal overviews when
             ``internal=True``, and external overviews when ``internal=False``.
         resample_method='near' (str): The resample method to use when
-            building overviews.  Must be one of
-            ``{_GDAL_WARP_ALGOS_FOR_HUMAN_EYES}``.
+            building overviews.  Must be one of,
+            'rms | mode | sum | q1 | near | q3 | average | cubicspline |
+            bilinear | max | med | min | cubic | lanczos'.
         overwrite=False (bool): Whether to overwrite existing overviews, if
             any exist.
         levels='auto' (sequence): A sequence of integer overview levels. If