docs: fix issues with autoapi and typehints

README.md

@@ -43,7 +43,7 @@ alt="Latest version on PyPI"/></a>
 
 ![](docs/cover_fig.png)
 
-## Disclaimer
+# Disclaimer
 
 <p align="center">
 🚨 **Ready for daily use but still changing.** 🚨
@@ -63,7 +63,7 @@ You can use it to download common datasets (i.e. BedMachine, Bedmap2, MODIS Mosa
 
 Feel free to use, share, modify, and [contribute](https://polartoolkit.readthedocs.io/en/latest/contributing.html) to this project.
 
-### What _PolarToolkit_ is for:
+## What _PolarToolkit_ is for:
 
 - download commonly used datasets related to Antarctica, Greenland and the Arctic
 - making publication-quality maps and cross-sections
@@ -73,7 +73,7 @@ Feel free to use, share, modify, and [contribute](https://polartoolkit.readthedo
 - current focus for datasets is related to ice, geophysics, and earth properties since this is where my personal research interests are, but please request or add your own types of data!
 - basic geospatial manipulations (filtering, resampling, reprojecting, masking etc.)
 
-### What _PolarToolkit_ is **NOT** for:
+## What _PolarToolkit_ is **NOT** for:
 
 - downloading niche datasets or those that only cover specific regions
 - downloaded datasets outside of Antarctica, Greenland and the Arctic
@@ -90,7 +90,7 @@ Feel free to use, share, modify, and [contribute](https://polartoolkit.readthedo
 
 <!-- SPHINX-END-long-desc -->
 
-## How to contribute
+# How to contribute
 I welcome all forms of contribution! If you have any questions, comments or suggestions, please open a [discussion](https://github.com/mdtanker/polartoolkit/discussions/new/choose) or [issue (feature request)](https://github.com/mdtanker/polartoolkit/issues/new/choose)!
 
 Also, please feel free to share how you're using PolarToolkit, I'd love to know.

docs/_polartoolkit_refs.bib

@@ -181,6 +181,13 @@ @misc{dorschelinternational2022a
   langid = {english}
 }
 
+@misc{earthspy2024,
+  title = {Earthspy},
+  year = {2024},
+  abstract = {Monitor and study any place on Earth and in Near Real-Time using the Sentinel Hub services developed by the EO research team at Sinergise},
+  howpublished = {https://github.com/AdrienWehrle/earthspy}
+}
+
 @misc{etopo12009,
   title = {{{ETOPO1}} 1 {{Arc-Minute Global Relief Model}}: {{Procedures}}, {{Data Sources}} and {{Analysis}}},
   year = {2009},
@@ -253,6 +260,22 @@ @article{fretwellbedmap22013
   file = {/home/mdtanker/Zotero/storage/KCURIVQ2/Fretwell et al_2013_Bedmap2.pdf;/home/mdtanker/Zotero/storage/TP44MVBH/Fretwell et al_2013_Bedmap2.pdf}
 }
 
+@misc{gerrishcoastline2020,
+  title = {The Coastline of {{Kalaallit Nunaat}}/ {{Greenland}} Available as a Shapefile and Geopackage, Covering the Main Land and Islands, with Glacier Fronts Updated as of 2017.},
+  author = {Gerrish, Laura},
+  year = {2020},
+  month = dec,
+  pages = {2 files, 5.26 MB},
+  publisher = {[object Object]},
+  doi = {10.5285/8CECDE06-8474-4B58-A9CB-B820FA4C9429},
+  urldate = {2024-05-09},
+  abstract = {A coastline of Kalaallit Nunaat/ Greenland covering all land and islands, produced in 2017 for the BAS map 'Greenland and the European Arctic'. The dataset was produced by extracting the land mask from the Greenland BedMachine dataset and manually editing anomalous data. Some missing islands were added and glacier fronts were updated using 2017 satellite imagery. The dataset can be used for cartography, analysis and as a mask, amongst other uses. At very large scales, the data will appear angular due to the nature of being extracted from a raster with 150 m cell size, but the dataset should be suitable for use at most scales and can be edited by the user to exclude very small islands if required. The projection of the dataset is WGS 84 NSIDC Sea Ice Polar Stereographic North, EPSG 3413. The dataset does not promise to cover every island and coastlines were digitised using the data creator's interpretation of the landforms from the images.},
+  collaborator = {Gerrish, Laura and Gerrish, Laura and {UK Polar Data Centre} and {UK Polar Data Centre} and {UK Polar Data Centre}},
+  copyright = {Open Government Licence V3.0},
+  langid = {english},
+  keywords = {"EARTH SCIENCE""CRYOSPHERE""GLACIERS/ICE SHEETS","EARTH SCIENCE""OCEANS""COASTAL PROCESSES""SHORELINES",Coastline,Greenland,Land cover,Topography}
+}
+
 @incollection{golynskyadmap2006,
   title = {{{ADMAP}} --- {{A Digital Magnetic Anomaly Map}} of the {{Antarctic}}},
   booktitle = {Antarctica: {{Contributions}} to {{Global Earth Sciences}}},
@@ -297,6 +320,41 @@ @misc{golynskyadmap22018a
   langid = {english}
 }
 
+@article{golynskynew2018,
+  title = {New {{Magnetic Anomaly Map}} of the {{Antarctic}}: {{ADMAP2}}},
+  author = {Golynsky, A. V. and Ferraccioli, F. and Hong, J. K. and Golynsky, D. A. and {von Frese}, R. R. B. and Young, D. A. and Blankenship, D. D. and Holt, J. W. and Ivanov, S. V. and Kiselev, A. V. and Masolov, V. N. and Eagles, G. and Gohl, K. and Jokat, W. and Damaske, D. and Finn, C. and Aitken, A. and Bell, R. E. and Armadillo, E. and Jordan, T. A. and Greenbaum, J. S. and Bozzo, E. and Caneva, G. and Forsberg, R. and Ghidella, M. and {Galindo-Zaldivar}, J. and Bohoyo, F. and Martos, Y. M. and Nogi, Y. and Quartini, E. and Kim, H. R. and Roberts, J. L.},
+  year = {2018},
+  month = jul,
+  journal = {Geophysical Research Letters},
+  volume = {45},
+  number = {13},
+  pages = {6437--6449},
+  issn = {00948276},
+  doi = {10.1029/2018GL078153},
+  urldate = {2020-01-06},
+  langid = {english},
+  file = {/home/mdtanker/Zotero/storage/DAEZI58R/Golynsky et al_2018_New Magnetic Anomaly Map of the Antarctic.pdf}
+}
+
+@misc{haranmeasures2018,
+  title = {{{MEaSUREs MODIS Mosaic}} of {{Greenland}} ({{MOG}}) 2005, 2010, and 2015 {{Image Maps}}, {{Version}} 2},
+  author = {Haran, T. and Bohlander, J. and Scambos, T. A. and Painter, T. and Fahnestock, M.},
+  year = {2018},
+  publisher = {{NASA National Snow and Ice Data Center Distributed Active Archive Center}},
+  doi = {10.5067/9ZO79PHOTYE5},
+  urldate = {2024-04-30},
+  langid = {english}
+}
+
+@misc{haranmodis2021,
+  title = {{{MODIS Mosaic}} of {{Antarctica}} 2008-2009 ({{MOA2009}}) {{Image Map}}, {{Version}} 2},
+  author = {Haran, T. and Bohlander, J. and Scambos, T A and Painter, T. and Fahnestock, M.},
+  year = {2021},
+  doi = {10.5067/4ZL43A4619AF},
+  urldate = {2024-01-31},
+  langid = {english}
+}
+
 @article{howatreference2019,
   title = {The {{Reference Elevation Model}} of {{Antarctica}}},
   author = {Howat, Ian M. and Porter, Claire and Smith, Benjamin E. and Noh, Myoung-Jong and Morin, Paul},
@@ -332,6 +390,23 @@ @article{hoyerxarray2017
   file = {/home/mdtanker/Zotero/storage/AQE75E62/Hoyer and Hamman - 2017 - xarray N-D labeled Arrays and Datasets in Python.pdf}
 }
 
+@misc{icebridge2020a,
+  title = {{{IceBridge BedMachine Greenland}}, {{Version}} 5},
+  year = {2020},
+  month = oct,
+  journal = {National Snow and Ice Data Center},
+  urldate = {2024-06-10},
+  howpublished = {https://nsidc.org/data/idbmg4/versions/5},
+  langid = {english}
+}
+
+@misc{itslive2024,
+  title = {{{ITSLIVE}}},
+  year = {2024},
+  abstract = {Python client for ITSLIVE glacier ice velocities.},
+  howpublished = {https://github.com/nasa-jpl/itslive-py}
+}
+
 @article{leongdeepbedmap2020,
   title = {{{DeepBedMap}}: A Deep Neural Network for Resolving the Bed Topography of {{Antarctica}}},
   shorttitle = {{{DeepBedMap}}},
@@ -364,6 +439,23 @@ @misc{leongdeepbedmap2020a
   keywords = {Antarctica,Digital Elevation Model,Neural Network,Super-resolution}
 }
 
+@article{lindequepreglacial2016,
+  title = {Preglacial to Glacial Sediment Thickness Grids for the {{Southern Pacific Margin}} of {{West Antarctica}}: {{Preglacial}}, Transitional and Full Glacial Isopach Maps, {{West Antarctica}}},
+  shorttitle = {Preglacial to Glacial Sediment Thickness Grids for the {{Southern Pacific Margin}} of {{West Antarctica}}},
+  author = {Lindeque, Ansa and Gohl, Karsten and Wobbe, Florian and {Uenzelmann-Neben}, Gabriele},
+  year = {2016},
+  journal = {Geochemistry, Geophysics, Geosystems},
+  volume = {17},
+  number = {10},
+  pages = {4276--4285},
+  issn = {15252027},
+  doi = {10.1002/2016GC006401},
+  urldate = {2020-07-23},
+  abstract = {Circum-Antarctic sediment thickness grids provide constraints for basin evolution and paleotopographic reconstructions, which are important for paleo-ice sheet formation histories. By compiling old and new seismic data, we identify sequences representing preglacial, transitional, and full glacial deposition processes along the Pacific margin of West Antarctica. The preglacial sediment grid depicts 1.3--4.0 km thick depocenters, relatively evenly distributed along the margin. The depocenters change markedly in the transitional phase at, or after, the Eocene/Oligocene boundary when the first major ice sheets reached the shelf. Full glacial sequences, starting in the middle Miocene, indicate new depocenter formation North of the Amundsen Sea Embayment and localized eastward shifts in the Bellingshausen Sea and Antarctic Peninsula basins. Using present-day drainage paths and source areas on the continent, our calculations indicate that an estimated observed total sedimentary volume of  10 3 106 km3 was eroded from West Antarctica since the separation of New Zealand in the Late Cretaceous. Of this, 4.9 3 106 km3 predates the onset of glaciation and need to be considered for a 34 Ma paleotopography reconstruction. Whereas 5.1 3 106 km3 postdates the onset of glaciation, of which 2.5 3 106 km3 were deposited in post mid-Miocene full glacial conditions.},
+  langid = {english},
+  file = {/home/mdtanker/Zotero/storage/IJMGPD55/Lindeque et al_2016_Preglacial to glacial sediment thickness grids for the Southern Pacific Margin.pdf;/home/mdtanker/Zotero/storage/S79S2RT4/Lindeque et al_2016_Preglacial to glacial sediment thickness grids for the Southern Pacific Margin.pdf}
+}
+
 @misc{lindequepreglacial2016a,
   title = {Pre-Glacial to Glacial Sediment Thickness Grids for the {{Southern Pacific Margin}} of {{West Antarctica}}, {{NetCDF}} Files},
   author = {Lindeque, Ansa and Gohl, Karsten and Wobbe, Florian and {Uenzelmann-Neben}, Gabriele},
@@ -451,12 +543,13 @@ @article{martosheat2017
   file = {/home/mdtanker/Zotero/storage/RPKK9T65/Martos et al_2017_Heat Flux Distribution of Antarctica Unveiled.pdf;/home/mdtanker/Zotero/storage/W7SISD39/Martos et al_2017_Heat Flux Distribution of Antarctica Unveiled.pdf}
 }
 
-@misc{modis2021,
-  title = {{{MODIS Mosaic}} of {{Antarctica}} 2008-2009 ({{MOA2009}}) {{Image Map}}, {{Version}} 2},
-  year = {2021},
+@misc{measures2020,
+  title = {{{MEaSUREs Multi-year Greenland Ice Sheet Velocity Mosaic}}, {{Version}} 1},
+  year = {2020},
+  month = oct,
   journal = {National Snow and Ice Data Center},
-  urldate = {2024-01-31},
-  howpublished = {https://nsidc.org/data/nsidc-0593/versions/2},
+  urldate = {2024-06-11},
+  howpublished = {https://nsidc.org/data/nsidc-0670/versions/1},
   langid = {english}
 }
 
@@ -558,6 +651,24 @@ @article{scambosmodisbased2007
   file = {/home/mdtanker/Zotero/storage/QX37N8VJ/scambos_2007_modis-based_mosaic_of_antarctica_(moa)_data_sets.pdf}
 }
 
+@article{scheickicepyx2023,
+  title = {Icepyx: Querying, Obtaining, Analyzing, and Manipulating {{ICESat-2}} Datasets},
+  shorttitle = {Icepyx},
+  author = {Scheick, Jessica and Leong, Wei Ji and Bisson, Kelsey and Arendt, Anthony and Bhushan, Shashank and Fair, Zachary and Hagen, Norland Raphael and Henderson, Scott and Knuth, Friedrich and Li, Tian and Liu, Zheng and Piunno, Romina and Ravinder, Nitin and Landung and Sutterley, Tyler and Swinski, Jp and Anubhav},
+  year = {2023},
+  month = apr,
+  journal = {Journal of Open Source Software},
+  volume = {8},
+  number = {84},
+  pages = {4912},
+  issn = {2475-9066},
+  doi = {10.21105/joss.04912},
+  urldate = {2024-06-14},
+  abstract = {Scheick et al., (2023). icepyx: querying, obtaining, analyzing, and manipulating ICESat-2 datasets. Journal of Open Source Software, 8(84), 4912, https://doi.org/10.21105/joss.04912},
+  langid = {english},
+  file = {/home/mdtanker/Zotero/storage/U8IRP8HU/Scheick et al. - 2023 - icepyx querying, obtaining, analyzing, and manipu.pdf}
+}
+
 @article{scheinertnew2016,
   title = {New {{Antarctic}} Gravity Anomaly Grid for Enhanced Geodetic and Geophysical Studies in {{Antarctica}}},
   author = {Scheinert, M. and Ferraccioli, F. and Schwabe, J. and Bell, R. and Studinger, M. and Damaske, D. and Jokat, W. and Aleshkova, N. and Jordan, T. and Leitchenkov, G. and Blankenship, D. D. and Damiani, T. M. and Young, D. and Cochran, J. R. and Richter, T. D.},
@@ -575,6 +686,18 @@ @article{scheinertnew2016
   file = {/home/mdtanker/Zotero/storage/7NGTWTU7/grl53915-sup-0001-supplementary.pdf;/home/mdtanker/Zotero/storage/G2J2WIA3/Scheinert et al_2016_New Antarctic gravity anomaly grid for enhanced geodetic and geophysical.pdf}
 }
 
+@misc{shaperoicepack2023,
+  title = {Icepack/Icepack: Data Assimilation Improvements},
+  shorttitle = {Icepack/Icepack},
+  author = {Shapero, Daniel and Lilien, David and Badgeley, Jessica and Hoffman, Andrew and Ham, David A. and Hills, Ben},
+  year = {2023},
+  month = may,
+  doi = {10.5281/zenodo.7897023},
+  urldate = {2024-06-14},
+  abstract = {This release improves the data assimilation routines: You can now supply a list of loss and regularization functionals. They get assembled separately and then summed together. This works around a limitation in Firedrake where you can't assemble the sum of a point data integral and a volume integral. The ROL shims have been fixed for the new version.},
+  howpublished = {Zenodo}
+}
+
 @article{shencrust2018,
   title = {The Crust and Upper Mantle Structure of {{Central}} and {{West Antarctica}} from Bayesian Inversion of {{Rayleigh}} Wave and Receiver Functions},
   author = {Shen, Weisen and Wiens, Douglas A. and Anandakrishnan, Sridhar and Aster, Richard C. and Gerstoft, Peter and Bromirski, Peter D. and Hansen, Samantha E. and Dalziel, Ian W. D. and Heeszel, David S. and Huerta, Audrey D. and Nyblade, Andrew A. and Stephen, Ralph and Wilson, Terry J. and Winberry, J. Paul},
@@ -742,6 +865,18 @@ @article{tintoross2019
   file = {/home/mdtanker/Zotero/storage/STWUNIFP/Tinto et al_2019_Ross Ice Shelf response to climate driven by the tectonic imprint on seafloor.pdf;/home/mdtanker/Zotero/storage/ZTYVRTXS/Tinto et al_2019_Ross Ice Shelf response to climate driven by the tectonic imprint on seafloor.pdf}
 }
 
+@misc{uiedafatiando2022,
+  title = {Fatiando a {{Terra Data}}: {{Earth}} - {{Topography}} Grid at 10 Arc-Minute Resolution},
+  shorttitle = {Fatiando a {{Terra Data}}},
+  author = {Uieda, Leonardo},
+  year = {2022},
+  month = jan,
+  publisher = {Zenodo},
+  doi = {10.5281/zenodo.5882203},
+  urldate = {2024-06-03},
+  abstract = {Global 10 arc-minute resolution grids of topography (ETOPO1 ice-surface) referenced to mean sea-level (which we will consider to be the geoid). Note: This is a processed and formatted version of the source dataset below. It's meant for use in documentation and tutorials of the Fatiando a Terra project. Please cite the original authors when using this dataset. Changes made: Convert the grid from the ASCII format of ICGEM to CF-compliant netCDF. Add relevant metadata, including names, units, datum, etc. Fix grid coordinates to be generated by numpy.linspace instead numpy.arange (or the equivalent used by ICGEM internally) to guarantee equal spacing to a higher accuracy. Export to compressed netCDF. Source:~ETOPO1 (grid generated by the ICGEM calculation service) Source license: public domain Repository: https://github.com/fatiando-data/earth-topography-10arcmin}
+}
+
 @article{uiedapooch2020,
   title = {Pooch: {{A}} Friend to Fetch Your Data Files},
   shorttitle = {Pooch},

docs/conf.py

@@ -21,18 +21,17 @@
 author = "Matt Tankersley"
 version = release = polartoolkit.__version__
 extensions = [
-    "sphinx.ext.napoleon",
-    "sphinx.ext.autodoc",
+    "sphinx.ext.autodoc",  # needed for typehints
+    "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "autoapi.extension",
     "sphinx.ext.mathjax",
-    "sphinx_autodoc_typehints",
     "sphinx_copybutton",
     "myst_parser",
     "sphinx_design",
     "nbsphinx",
-    "sphinx.ext.viewcode",
     "sphinxcontrib.bibtex",
-    # "sphinx.ext.autosummary",
 ]
 source_suffix = [".rst", ".md"]
 exclude_patterns = [
@@ -67,18 +66,26 @@
     "numba": ("https://numba.pydata.org/numba-doc/latest/", None),
     "scipy": ("https://docs.scipy.org/doc/scipy/", None),
     "pyvista": ("https://docs.pyvista.org/", None),
+    "pooch": ("https://www.fatiando.org/pooch/latest/", None),
+    "cartopy": ("https://scitools.org.uk/cartopy/docs/latest/", None),
     # "tqdm": ("https://tqdm.github.io/", None),
     "pygmt": ("https://www.pygmt.org/latest/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
+    "geopandas": ("https://geopandas.org/en/stable/", None),
     #
     # Viz deps
     #
     "seaborn": ("https://seaborn.pydata.org/", None),
+    "ipyleaflet": ("https://ipyleaflet.readthedocs.io/en/latest/", None),
+    "holoviews": ("http://holoviews.org/", None),
+    "geoviews": ("http://geoviews.org/", None),
 }
 
 nitpick_ignore = [
     ("py:class", "_io.StringIO"),
     ("py:class", "_io.BytesIO"),
+    ("py:class", "optional"),
+    ("py:class", "Ellipsis"),
 ]
 
 always_document_param_types = True
@@ -87,19 +94,15 @@
 
 # API doc configuration
 # -----------------------------------------------------------------------------
-# autosummary_generate = True
-# autodoc_default_options = {
-#     "members": True,
-#     "show-inheritance": True,
-# }
-# apidoc_module_dir = '../src/polartoolkit'
-# apidoc_excluded_paths = ['tests']
-# apidoc_separate_modules = False
+autoapi_dirs = ["../src/polartoolkit"]
+autoapi_type = "python"
+autoapi_add_toctree_entry = False
+autodoc_typehints = "description"
+
 
 # HTML output configuration
 # -----------------------------------------------------------------------------
 html_title = f'{project} <span class="project-version">{version}</span>'
-# html_logo = "logo.png"
 html_static_path = []
 html_favicon = "logo_dark.png"
 html_last_updated_fmt = "%b %d, %Y"

docs/contributing.md

@@ -238,16 +238,14 @@ If your edits haven't changed any part of the core package, then there is no nee
 
 #### Check the build manually (optional)
 
-You can build the docs using, but this will require pandoc to be install on your machine:
-
+You can build the docs using:
 ```bash
-nox -s docs
+    nox -s docs
 ```
 
-You can see a preview with:
-
+or if you don't want them to automatically update
 ```bash
-nox -s docs -- --serve
+    nox -s docs --non-interactive
 ```
 
 #### Automatically build the docs