Add pixel_ratio option to .to_raster() (#1354)

* Add `pixel_ratio` to `.to_raster`

* Really float

* Add a way to pass in known pixel mapping

if plotting same scene again, say
or tweaking a plot

* Add some geoax annotations

* Doc new parameters in the public docstring

* Add example

* Fix numba source

* fmt

* Remove extent prints

* Add Cartopy intersphinx

* Ignore more files generated in the docs build

* Add a few exclude patterns

mainly for temporary notebook files that may be around

* Add some cross refs

* Add pixel ratio test

* Expand mapping description

* Add DPI note

* Update internal docstrings

* Test consistent nan frac

* Simplify gallery gitignore a bit

* sp

* Update caution note

* More intersphinx etc.

* Fix the PolyCollection example for now

. #1356

* More gitignore

* Add subset -> PolyCollection example

* flatnonzero applies ravel

* Move the degenerate poly filter into the polycollection func

* Set up API

* Ensure passing ndarray; check pixel_ratio

* cleanup

* Add example

* Add some tests

* TypeError seems more appropriate

* Fix ref

* Update Cartopy intersphinx

* stable intersphinx

what the majority of users (and devs, I would think), would want

the redirects are not followed, for example:

intersphinx inventory 'https://numba.readthedocs.io/objects.inv' not fetchable due to <class 'requests.exceptions.HTTPError'>: 404 Client Error: Not Found for url: https://numba.readthedocs.io/objects.inv

* Validate the pixel mapping for usage with ax

and encapsulate

note that `ccrs.CRS(str(ax.projection))` can recover the proj
in many cases, but not all

* Move some comparison code to the class

* Add some docstrings; test attr recovery

Author: zmoon

.gitignore

@@ -141,6 +141,7 @@ test/dask-worker-space/
 /dask-worker-space/
 .vscode/
 generated/
+.ipynb_checkpoints/
 
 # Test grid files.
 test/meshfiles/*.g
@@ -150,9 +151,13 @@ test/write_*
 
 # Autogenerated docs
 docs/user_api/_autosummary/
-
 docs/notebook-examples.txt
-
+docs/*-examples-gallery.txt
+docs/user-guide/oQU120.data.nc
+docs/user-guide/oQU120.grid.nc
+docs/user-guide/oQU480.data.nc
+docs/user-guide/oQU480.grid.nc
+docs/user-guide/psi_healpix.nc
 
 # benchmarking
 benchmarks/env

docs/conf.py

@@ -74,17 +74,18 @@ def __getattr__(cls, name):
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
-    "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
-    "iris": ("https://scitools-iris.readthedocs.io/en/latest", None),
-    "numpy": ("https://numpy.org/doc/stable", None),
-    "scipy": ("https://docs.scipy.org/doc/scipy", None),
-    "numba": ("https://numba.pydata.org/numba-doc/latest", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+    "iris": ("https://scitools-iris.readthedocs.io/en/stable/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "numba": ("https://numba.readthedocs.io/en/stable/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
-    "dask": ("https://docs.dask.org/en/latest", None),
-    "cftime": ("https://unidata.github.io/cftime", None),
-    "rasterio": ("https://rasterio.readthedocs.io/en/latest", None),
-    "sparse": ("https://sparse.pydata.org/en/latest/", None),
-    "xarray": ("http://xarray.pydata.org/en/stable/", None),
+    "dask": ("https://docs.dask.org/en/stable/", None),
+    "cftime": ("https://unidata.github.io/cftime/", None),
+    "rasterio": ("https://rasterio.readthedocs.io/en/stable/", None),
+    "sparse": ("https://sparse.pydata.org/en/stable/", None),
+    "xarray": ("https://docs.xarray.dev/en/stable/", None),
+    "cartopy": ("https://cartopy.readthedocs.io/stable/", None),
 }
 
 
@@ -136,7 +137,7 @@ def __getattr__(cls, name):
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ["_build", "**.ipynb_checkpoints"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"