Improvements to doc build process (#647)

Author: ianthomas23

.github/workflows/docs-publish.yml

@@ -18,6 +18,7 @@ jobs:
       - name: Build
         run: |
           pip install .
+          pip list
           make -C docs html
       - uses: lauchacarro/Azure-Storage-Action@v1.0
         with:

docs/source/conf.py

@@ -47,6 +47,7 @@
     'sphinx_multiversion',
     'nbsphinx',
     'sphinx.ext.mathjax',
+    'matplotlib.sphinxext.plot_directive',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -86,7 +87,6 @@
     html_theme = 'sphinx_rtd_theme'
 else:
     html_theme = 'pydata_sphinx_theme'
-    extensions.append('matplotlib.sphinxext.plot_directive')
 
 html_logo = '_static/img/Xarray-Spatial-logo.svg'
 
@@ -95,9 +95,9 @@
 # sphinx-multiversion config
 smv_branch_whitelist = 'master'
 if os.getenv('THEME') == 'sphinx_rtd_theme':
-    smv_tag_whitelist = r'^v([0]\.[1]\.[0-5]|[0]\.[0]\.[0-9])'
+    smv_tag_whitelist = r'^v([0-9]\.[2-9]\.[0-9])'
 else:
-    smv_tag_whitelist = r'^v([0]\.[1]\.[6-9]|[0-9]\.[2-9]\.[0-9])'
+    smv_tag_whitelist = r'^v([0-9]\.[2-9]\.[0-9])'
 
 # Load releases
 with open("releases.json") as f:

xrspatial/aspect.py

@@ -172,6 +172,7 @@ def aspect(agg: xr.DataArray,
     --------
     Aspect works with NumPy backed xarray DataArray
     .. sourcecode:: python
+
         >>> import numpy as np
         >>> import xarray as xr
         >>> from xrspatial import aspect
@@ -207,6 +208,7 @@ def aspect(agg: xr.DataArray,
 
     Aspect works with Dask with NumPy backed xarray DataArray
     .. sourcecode:: python
+
         >>> import dask.array as da
         >>> data_da = da.from_array(data, chunks=(3, 3))
         >>> raster_da = xr.DataArray(data_da, dims=['y', 'x'], name='raster_da')
@@ -232,6 +234,7 @@ def aspect(agg: xr.DataArray,
     Aspect works with CuPy backed xarray DataArray.
     Make sure you have a GPU and CuPy installed to run this example.
     .. sourcecode:: python
+
         >>> import cupy
         >>> data_cupy = cupy.asarray(data)
         >>> raster_cupy = xr.DataArray(data_cupy, dims=['y', 'x'])

xrspatial/classify.py

@@ -207,6 +207,7 @@ def reclassify(agg: xr.DataArray,
     --------
     Reclassify works with NumPy backed xarray DataArray
     .. sourcecode:: python
+
         >>> import numpy as np
         >>> import xarray as xr
         >>> from xrspatial.classify import reclassify
@@ -238,6 +239,7 @@ def reclassify(agg: xr.DataArray,
 
     Reclassify works with Dask with NumPy backed xarray DataArray
     .. sourcecode:: python
+
         >>> import dask.array as da
         >>> data_da = da.from_array(data, chunks=(3, 3))
         >>> agg_da = xr.DataArray(data_da, name='agg_da')
@@ -261,6 +263,7 @@ def reclassify(agg: xr.DataArray,
     Reclassify works with CuPy backed xarray DataArray.
     Make sure you have a GPU and CuPy installed to run this example.
     .. sourcecode:: python
+
         >>> import cupy
         >>> data_cupy = cupy.asarray(data)
         >>> agg_cupy = xr.DataArray(data_cupy)
@@ -357,6 +360,7 @@ def quantile(agg: xr.DataArray,
     --------
     Quantile work with numpy backed xarray DataArray
     .. sourcecode:: python
+
         >>> import numpy as np
         >>> import xarray as xr
         >>> from xrspatial.classify import quantile
@@ -628,6 +632,7 @@ def natural_breaks(agg: xr.DataArray,
     -------
     natural_breaks() works with numpy backed xarray DataArray.
     .. sourcecode:: python
+
         >>> import numpy as np
         >>> import xarray as xr
         >>> from xrspatial.classify import natural_breaks
@@ -654,6 +659,7 @@ def natural_breaks(agg: xr.DataArray,
 
     natural_breaks() works with cupy backed xarray DataArray.
     .. sourcecode:: python
+
         >>> import cupy
         >>> agg_cupy = xr.DataArray(cupy.asarray(elevation))
         >>> cupy_natural_breaks = natural_breaks(agg_cupy)
@@ -750,6 +756,7 @@ def equal_interval(agg: xr.DataArray,
     Examples
     --------
     .. sourcecode:: python
+
         >>> import numpy as np
         >>> import xarray as xr
         >>> from xrspatial.classify import equal_interval

xrspatial/convolution.py

@@ -100,6 +100,7 @@ def calc_cellsize(raster):
     Examples
     --------
     .. sourcecode:: python
+
         >>> import numpy as np
         >>> import xarray as xr
         >>> h, w = 100, 200
@@ -417,6 +418,7 @@ def convolution_2d(agg, kernel, name='convolution_2d'):
     --------
     convolution_2d() works with NumPy backed DataArray.
     .. sourcecode:: python
+
         >>> import numpy as np
         >>> import xarray as xr
         >>> from xrspatial.convolution import circle_kernel
@@ -447,6 +449,7 @@ def convolution_2d(agg, kernel, name='convolution_2d'):
 
     convolution_2d() works with Dask with NumPy backed DataArray.
     .. sourcecode:: python
+
         >>> from xrspatial.convolution import annulus_kernel
         >>> kernel = annulus_kernel(1, 1, 1.5, 0.5)
         >>> kernel
@@ -474,6 +477,7 @@ def convolution_2d(agg, kernel, name='convolution_2d'):
 
     convolution_2d() works with CuPy backed DataArray.
     .. sourcecode:: python
+
         >>> from xrspatial.convolution import custom_kernel
         >>> kernel = custom_kernel(np.array([
         ...    [1, 0, 0],

xrspatial/curvature.py

@@ -125,6 +125,7 @@ def curvature(agg: xr.DataArray,
     --------
     Curvature works with NumPy backed xarray DataArray
     .. sourcecode:: python
+
         >>> import numpy as np
         >>> import xarray as xr
         >>> from xrspatial import curvature
@@ -144,6 +145,7 @@ def curvature(agg: xr.DataArray,
 
     Curvature works with Dask with NumPy backed xarray DataArray
     .. sourcecode:: python
+
         >>> convex_data = np.array([
             [0, 0, 0, 0, 0],
             [0, 0, 0, 0, 0],
@@ -179,6 +181,7 @@ def curvature(agg: xr.DataArray,
 
     Curvature works with CuPy backed xarray DataArray.
     .. sourcecode:: python
+
         >>> import cupy
         >>> concave_data = np.array([
             [0, 0, 0, 0, 0],

xrspatial/focal.py

@@ -137,6 +137,7 @@ def mean(agg, passes=1, excludes=[np.nan], name='mean'):
     --------
     Focal mean works with NumPy backed xarray DataArray
     .. sourcecode:: python
+
         >>> import numpy as np
         >>> import xarray as xr
         >>> from xrspatial.focal import mean
@@ -160,6 +161,7 @@ def mean(agg, passes=1, excludes=[np.nan], name='mean'):
     Focal mean works with Dask with NumPy backed xarray DataArray.
     Increase number of runs by setting a specific value for parameter `passes`
     .. sourcecode:: python
+
         >>> import dask.array as da
         >>> data_da = da.from_array(data, chunks=(3, 3))
         >>> raster_da = xr.DataArray(data_da, dims=['y', 'x'], name='raster_da')  # noqa
@@ -185,6 +187,7 @@ def mean(agg, passes=1, excludes=[np.nan], name='mean'):
     In this example, we set `passes` to the number of elements of the array,
     we'll get a mean array where every element has the same value.
     .. sourcecode:: python
+
         >>> import cupy
         >>> raster_cupy = xr.DataArray(cupy.asarray(data), name='raster_cupy')
         >>> mean_cupy = mean(raster_cupy, passes=25)
@@ -336,6 +339,7 @@ def apply(raster, kernel, func=_calc_mean, name='focal_apply'):
     --------
     Focal apply works with NumPy backed xarray DataArray
     .. sourcecode:: python
+
         >>> import numpy as np
         >>> import xarray as xr
         >>> from xrspatial.convolution import circle_kernel
@@ -368,7 +372,9 @@ def apply(raster, kernel, func=_calc_mean, name='focal_apply'):
     the applied function must be decorated with ``numba.jit``
     xrspatial already provides ``ngjit`` decorator, where:
     ``ngjit = numba.jit(nopython=True, nogil=True)``
+
     .. sourcecode:: python
+
     >>> from xrspatial.utils import ngjit
     >>> from xrspatial.convolution import custom_kernel
     >>> kernel = custom_kernel(np.array([
@@ -470,6 +476,7 @@ def focal_stats(agg,
     Examples
     --------
     .. sourcecode:: python
+
         >>> import numpy as np
         >>> import xarray as xr
         >>> from xrspatial.convolution import circle_kernel
@@ -700,6 +707,7 @@ def hotspots(raster, kernel):
     Examples
     --------
     .. sourcecode:: python
+
         >>> import numpy as np
         >>> import xarray as xr
         >>> from xrspatial.convolution import custom_kernel

xrspatial/hillshade.py

@@ -134,6 +134,7 @@ def hillshade(agg: xr.DataArray,
     Examples
     --------
     .. sourcecode:: python
+
         >>> import numpy as np
         >>> import xarray as xr
         >>> from xrspatial import hillshade

xrspatial/multispectral.py

@@ -106,8 +106,10 @@ def arvi(nir_agg: xr.DataArray,
     Examples
     --------
     In this example, we'll use data available in xrspatial.datasets
+
     .. plot::
        :include-source:
+
         >>> from xrspatial.datasets import get_data
         >>> data = get_data('sentinel-2')  # Open Example Data
         >>> nir = data['NIR']
@@ -122,6 +124,7 @@ def arvi(nir_agg: xr.DataArray,
         >>> arvi_agg.plot(aspect=2, size=4)
 
     .. sourcecode:: python
+
         >>> y1, x1, y2, x2 = 100, 100, 103, 104
         >>> print(nir[y1:y2, x1:x2].data)
         [[1519. 1504. 1530. 1589.]
@@ -270,6 +273,7 @@ def evi(nir_agg: xr.DataArray,
         >>> evi_agg.plot(aspect=2, size=4)
 
     .. sourcecode:: python
+
         >>> y, x = 100, 100
         >>> m, n = 3, 4
         >>> print(nir[y1:y2, x1:x2].data)
@@ -409,6 +413,7 @@ def gci(nir_agg: xr.DataArray,
         >>> gci_agg.plot(aspect=2, size=4)
 
     .. sourcecode:: python
+
         >>> y1, x1, y2, x2 = 100, 100, 103, 104
         >>> print(nir[y1:y2, x1:x2].data)
         [[1519. 1504. 1530. 1589.]
@@ -472,6 +477,7 @@ def nbr(nir_agg: xr.DataArray,
     --------
     .. plot::
        :include-source:
+
         >>> from xrspatial.datasets import get_data
         >>> data = get_data('sentinel-2')  # Open Example Data
         >>> nir = data['NIR']
@@ -484,6 +490,7 @@ def nbr(nir_agg: xr.DataArray,
         >>> nbr_agg.plot(aspect=2, size=4)
 
     .. sourcecode:: python
+
         >>> y1, x1, y2, x2 = 100, 100, 103, 104
         >>> print(nir[y1:y2, x1:x2].data)
         [[1519. 1504. 1530. 1589.]
@@ -554,6 +561,7 @@ def nbr2(swir1_agg: xr.DataArray,
     --------
     .. plot::
        :include-source:
+
         >>> from xrspatial.datasets import get_data
         >>> data = get_data('sentinel-2')  # Open Example Data
         >>> swir1 = data['SWIR1']
@@ -566,6 +574,7 @@ def nbr2(swir1_agg: xr.DataArray,
         >>> nbr2_agg.plot(aspect=2, size=4)
 
     .. sourcecode:: python
+
         >>> y1, x1, y2, x2 = 100, 100, 103, 104
         >>> print(swir1[y1:y2, x1:x2].data)
         [[2092. 2242. 2333. 2382.]
@@ -630,7 +639,7 @@ def ndvi(nir_agg: xr.DataArray,
     --------
     .. plot::
        :include-source:
-        >>> from xrspatial.datasets import get_data        
+        >>> from xrspatial.datasets import get_data
         >>> data = get_data('sentinel-2')  # Open Example Data
         >>> nir = data['NIR']
         >>> red = data['Red']
@@ -642,6 +651,7 @@ def ndvi(nir_agg: xr.DataArray,
         >>> ndvi_agg.plot(aspect=2, size=4)
 
     .. sourcecode:: python
+
         >>> y1, x1, y2, x2 = 100, 100, 103, 104
         >>> print(nir[y1:y2, x1:x2].data)
         [[1519. 1504. 1530. 1589.]
@@ -710,6 +720,7 @@ def ndmi(nir_agg: xr.DataArray,
     --------
     .. plot::
        :include-source:
+
         >>> from xrspatial.datasets import get_data
         >>> data = get_data('sentinel-2')  # Open Example Data
         >>> nir = data['NIR']
@@ -722,6 +733,7 @@ def ndmi(nir_agg: xr.DataArray,
         >>> ndmi_agg.plot(aspect=2, size=4)
 
     .. sourcecode:: python
+
         >>> y1, x1, y2, x2 = 100, 100, 103, 104
         >>> print(nir[y1:y2, x1:x2].data)
         [[1519. 1504. 1530. 1589.]
@@ -892,6 +904,7 @@ def savi(nir_agg: xr.DataArray,
     --------
     .. plot::
        :include-source:
+
         >>> from xrspatial.datasets import get_data
         >>> data = get_data('sentinel-2')  # Open Example Data
         >>> nir = data['NIR']
@@ -904,6 +917,7 @@ def savi(nir_agg: xr.DataArray,
         >>> savi_agg.plot(aspect=2, size=4)
 
     .. sourcecode:: python
+
         >>> print(nir[y1:y2, x1:x2].data)
         [[1519. 1504. 1530. 1589.]
          [1491. 1473. 1542. 1609.]
@@ -1020,6 +1034,7 @@ def sipi(nir_agg: xr.DataArray,
     --------
     .. plot::
        :include-source:
+
         >>> from xrspatial.datasets import get_data
         >>> data = get_data('sentinel-2')  # Open Example Data
         >>> nir = data['NIR']
@@ -1034,6 +1049,7 @@ def sipi(nir_agg: xr.DataArray,
         >>> sipi_agg.plot(aspect=2, size=4)
 
     .. sourcecode:: python
+
         >>> y1, x1, y2, x2 = 100, 100, 103, 104
         >>> print(nir[y1:y2, x1:x2].data)
         [[1519. 1504. 1530. 1589.]
@@ -1357,6 +1373,7 @@ def true_color(r, g, b, nodata=1, c=10.0, th=0.125, name='true_color'):
     --------
     .. plot::
        :include-source:
+
         >>> from xrspatial.datasets import get_data
         >>> data = get_data('sentinel-2')  # Open Example Data
         >>> red = data['Red']