Merge branch 'bugfix-docs' into develop

Author: molinav

.github/workflows/basemap-for-manylinux.yml

@@ -349,6 +349,65 @@ jobs:
           name: coverage
           path: ${{ env.PKGDIR }}/htmlcov
 
+  docs:
+    needs: test
+    runs-on: ubuntu-latest
+    container: "pylegacy/python:3.8-debian-9"
+    steps:
+      -
+        name: Download checkout
+        uses: actions/download-artifact@v1
+        with:
+          name: checkout
+          path: .
+      -
+        name: Install doc requirements
+        run: |
+          cd ${{ env.PKGDIR }}
+          pip install -r requirements-doc.txt
+      -
+        name: Download build artifacts
+        uses: actions/download-artifact@v1
+        with:
+          name: artifacts-build-x64-3.8
+          path: ${{ env.PKGDIR }}/dist
+      -
+        name: Install package
+        run: |
+          cd ${{ env.PKGDIR }}
+          pip install dist/*-manylinux1*.whl
+      -
+        name: Run sphinx
+        run: |
+          cd ${{ env.PKGDIR }}
+          python -m sphinx doc/source public
+      -
+        name: Upload docs artifacts
+        uses: actions/upload-artifact@v1
+        with:
+          name: docs
+          path: ${{ env.PKGDIR }}/public
+      -
+        name: Upload github-pages artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          name: github-pages
+          path: ${{ env.PKGDIR }}/public
+
+  pages:
+    needs: docs
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - name: Deploy github-pages
+        uses: actions/deploy-pages@v2
+        id: deployment
+
   upload:
     strategy:
       matrix:

CHANGELOG.md

@@ -38,6 +38,7 @@ https://semver.org/spec/v2.0.0.html
   - Upgrade upper limit for `furo` to 2023.9.11.
   - Move dependency on `netCDF4` to `requirements-doc.txt`.
   - Set dependency on `cftime` explicitly in `requirements-doc.txt`.
+  - Set dependency on `scipy` explicitly in `requirements-doc.txt`.
 - Update lint dependencies:
   - Downgrade upper limit for `flake8` to 6.2.
   - Upgrade upper limit for `astropy` to 3.1.

README.md

@@ -16,7 +16,7 @@ Basic requirements are the following:
 Optional requirements include:
 
 * [OWSLib](https://github.com/geopython/OWSLib). It is needed for the
-  `Basemap.wmsimage` function.
+  method `Basemap.wmsimage`.
 
 * [Pillow](https://github.com/python-pillow/Pillow). It is needed for
   the methods `Basemap.bluemarble`, `Basemap.etopo`,
@@ -25,7 +25,7 @@ Optional requirements include:
 ## Installation
 
 The `basemap-data` and `basemap-data-hires` packages are available in
-PyPI and can be installed with [`pip`](https:/pip.pypa.io/):
+PyPI and can be installed with [`pip`](https://pip.pypa.io/):
 ```sh
 python -m pip install basemap-data
 python -m pip install basemap-data-hires
@@ -37,7 +37,8 @@ available in PyPI (architectures x86 and x64, Python 2.7 and 3.5+):
 python -m pip install basemap
 ```
 
-Otherwise, you will need to install `basemap` from source as follows:
+Otherwise, you will need to install `basemap` from its source hosted
+on GitHub as indicated in the following steps:
 
 1. Install pre-requisite Python modules:
    - [cython](https://github.com/cython/cython)
@@ -51,7 +52,8 @@ Otherwise, you will need to install `basemap` from source as follows:
    ```
 
 3. Build the [GEOS](https://github.com/libgeos/geos) library. You may
-   use the helper provided in `utils`, i.e.
+   use the helper provided in `utils`, (please note that you need
+   [`CMake`](https://cmake.org/) and a working C compiler in advance):
    ```sh
    export GEOS_DIR=<your desired location>
    python -c "import utils; utils.GeosLibrary('3.6.5').build(installdir='${GEOS_DIR}')"
@@ -70,11 +72,10 @@ Otherwise, you will need to install `basemap` from source as follows:
    to build Cython extensions (e.g. on Debian-like systems, you should
    have the package `python-dev` installed).
 
-5. Check that the package installed correctly by executing:
+5. Check that the package was installed correctly by executing:
    ```sh
    python -c "from mpl_toolkits.basemap import Basemap"
    ```
-   You can also test the examples available in the `examples` folder.
 
 ## License
 
@@ -98,7 +99,7 @@ https://spdx.org/licenses/LGPL-3.0-or-later.html
 
 ## Documentation
 
-See https://matplotlib.github.io/basemap/
+See https://matplotlib.org/basemap/
 
 See scripts in `examples` directory for example usage.
 

examples/geos_demo.py

@@ -20,11 +20,11 @@ def get_input(prompt):
 # plot land-sea mask.
 # land red, oceans blue.
 # lakes=True means plot inland lakes with ocean color.
+m.drawmapboundary()
 m.drawlsmask(land_color='red',ocean_color='blue',lakes=True)
 # draw parallels and meridians.
 m.drawparallels(np.arange(-90.,120.,30.))
 m.drawmeridians(np.arange(0.,420.,60.))
-m.drawmapboundary()
 plt.title('Geostationary Map Centered on Lon=%s' % (lon_0))
 
 # map with continents drawn and filled.

examples/geos_demo_2.py

@@ -39,7 +39,7 @@
 m = Basemap(projection='geos', lon_0=lon_0, satellite_height=satellite_height,
             resolution='l', llcrnrlon=ll_lon, llcrnrlat=ll_lat, urcrnrlon=ur_lon, urcrnrlat=ur_lat)
 # add data
-m.imshow(data, cmap=plt.cm.gray, interpolation='nearest')
+m.imshow(data[::-1], cmap=plt.cm.gray, interpolation='nearest')
 plt.clim(0, 255)
 # draw coastlines.
 m.drawcoastlines(linewidth=0.5, color=overlay_color)

examples/hurrtracks.py

@@ -1,22 +1,20 @@
-from __future__ import (absolute_import, division, print_function)
-
 """
 draw Atlantic Hurricane Tracks for storms that reached Cat 4 or 5.
 part of the track for which storm is cat 4 or 5 is shown red.
 ESRI shapefile data from http://nationalatlas.gov/mld/huralll.html
 """
+import os
 import numpy as np
 import matplotlib.pyplot as plt
-from mpl_toolkits.basemap import Basemap as Basemap
-# Lambert Conformal Conic maplt.
+from mpl_toolkits.basemap import Basemap
+# Lambert Conformal Conic map.
 m = Basemap(llcrnrlon=-100.,llcrnrlat=0.,urcrnrlon=-20.,urcrnrlat=57.,
             projection='lcc',lat_1=20.,lat_2=40.,lon_0=-60.,
             resolution ='l',area_thresh=1000.)
 # create figure.
 fig=plt.figure()
 # read shapefile.
 shp_info = m.readshapefile('huralll020','hurrtracks',drawbounds=False)
-print(shp_info)
 # find names of storms that reached Cat 4.
 names = []
 for shapedict in m.hurrtracks_info:
@@ -25,8 +23,6 @@
     if cat in ['H4','H5'] and name not in names:
         # only use named storms.
         if name != 'NOT NAMED':  names.append(name)
-print(names)
-print(len(names))
 # plot tracks of those storms.
 for shapedict,shape in zip(m.hurrtracks_info,m.hurrtracks):
     name = shapedict['NAME']

examples/ortho_demo.py

@@ -22,13 +22,13 @@ def get_input(prompt):
 # land coral, oceans aqua.
 # lakes=True means plot inland lakes with ocean color.
 # resolution = 5 (default) means use 5 min dataset (can use 2.5)
+m.drawmapboundary()
 m.drawcoastlines()
 m.drawlsmask(land_color='coral',ocean_color='aqua', lakes=True,\
         resolution=resolution,grid=grid)
 # draw parallels and meridians.
 m.drawparallels(np.arange(-90.,120.,30.))
 m.drawmeridians(np.arange(0.,420.,60.))
-m.drawmapboundary()
 plt.title('Orthographic Map Centered on Lon=%s, Lat=%s' % (lon_0,lat_0))
 
 # map with continents drawn and filled (continent filling fails for

examples/plotcities.py

@@ -1,20 +1,22 @@
 from __future__ import (absolute_import, division, print_function)
 
-from matplotlib.mlab import prctile_rank
+import numpy as np
 import matplotlib.pyplot as plt
 from mpl_toolkits.basemap import Basemap as Basemap
+prctile_rank = lambda x, p: np.searchsorted(np.percentile(x, np.atleast_1d(p)), x)
 
 # cities colored by population rank.
 
 m = Basemap()
 shp_info = m.readshapefile('cities','cities')
-x, y = zip(*m.cities)
-pop = []
-for item in m.cities_info:
+x, y, pop = [], [], []
+for item, (x_i, y_i) in zip(m.cities_info, m.cities):
     population = item['POPULATION']
-    if population < 0: continue # population missing
-    pop.append(population)
-popranks = prctile_rank(pop,100)
+    if population >= 0:
+        pop.append(population)
+        x.append(x_i)
+        y.append(y_i)
+popranks = prctile_rank(pop,np.linspace(0, 100, 101))
 colors = []
 for rank in popranks:
     colors.append(plt.cm.jet(float(rank)/100.))

examples/plothighsandlows.py

@@ -27,7 +27,7 @@ def main():
     """Main function."""
 
     # Plot 00 UTC today.
-    url = "http://nomads.ncep.noaa.gov/dods/gfs_0p25/gfs%Y%m%d/gfs_0p25_00z"
+    url = "http://nomads.ncep.noaa.gov/dods/gfs_0p50/gfs%Y%m%d/gfs_0p50_00z"
     date = dt.datetime.now()
 
     # Open OPeNDAP dataset.

examples/plotozone.py

@@ -66,7 +66,7 @@
 
 toplot = np.ma.masked_values(o3[0, 0], 0.) * 1000.
 bounds = np.percentile(toplot.compressed().ravel(), np.linspace(5, 95, 9).tolist())
-ptch = m.pcolor(X, Y, toplot, cmap = WhGrYlBu, norm = plt.matplotlib.colors.BoundaryNorm(bounds, 20), vmin = bounds[0], vmax = bounds[-1])
+ptch = m.pcolor(X, Y, toplot, cmap = WhGrYlBu, norm = plt.matplotlib.colors.BoundaryNorm(bounds, 20))
 
 # Add a colorbar using proportional spacing, but
 # colors based on 10 distinct bins