Docs for polygon interface (#362)

* initial stab at documenting polygon interface * Separate out verbose descriptions * Nicer flow * improvements * avoid using "set" * move compact functions * move geo functions * "grid distance" is better than "H3 distance" * lint * units * clean up contributing * warning about function name changes * don't need to specify title * update copyright * add a warning about lat/lng order * try this * give the geo_interface link * sphinx 7.3 introduced an issue * document bug * better organization of functions * green is a friendlier color * don't need this * sphinx bug is fixed with 7.3.3
uber · Apr 17, 2024 · 26285ef · 26285ef
1 parent cd59584
commit 26285ef
Show file tree

Hide file tree

Showing 11 changed files with 272 additions and 202 deletions.
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -1,11 +1,6 @@
-#######################################################################################
-# A default configuration that will be loaded for all jupyter books
-# See the documentation for help and more options:
-# https://jupyterbook.org/customize/config.html
-
 title: h3-py
 author: 'Uber Technologies'
-copyright: "2021"
+copyright: "2024"
 logo: logo.svg
 
 html:

diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -1,19 +1,16 @@
-# Table of contents
 # Learn more at https://jupyterbook.org/customize/toc.html
 format: jb-book
-
 root: intro
 parts:
 - caption: h3-py
   chapters:
-  - file: api_comparison
-  - file: api_reference
+  - file: api_quick
+  - file: api_verbose
   - file: polygon_tutorial
+  - file: api_comparison
 
 - caption: Sundries
   chapters:
   - file: _changelog
-    title: CHANGELOG
   - file: contributing
   - file: project_links
-    title: Project Links
diff --git a/docs/api_comparison.md b/docs/api_comparison.md
@@ -1,4 +1,4 @@
-# API Comparison
+# Comparison of APIs
 
 The `h3-py` library provides several APIs which share the same functions,
 but differ in their input and output types:

diff --git a/docs/api_quick.md b/docs/api_quick.md
@@ -0,0 +1,170 @@
+# API Quick Reference
+
+```{tip}
+Function names changed significantly with `h3-py` `v4.0` to align with the C library: https://h3geo.org/docs/library/migration-3.x/functions
+```
+
+We list the functions that are shared between the
+[provided APIs](api_comparison).
+The APIs differ only in their input/output types
+(e.g., `int` vs. `str` or `list` vs `numpy.array`).
+
+These functions correspond to those explained in the
+[H3 C library documentation](https://h3geo.org/docs/api/indexing),
+and should be generally aligned with the
+[other language bindings](https://h3geo.org/docs/community/bindings).
+
+## Identification
+
+```{eval-rst}
+.. currentmodule:: h3
+
+.. autosummary::
+   is_valid_cell
+   is_pentagon
+   is_res_class_III
+   is_valid_directed_edge
+```
+
+## Index representation
+
+```{eval-rst}
+.. currentmodule:: h3
+
+.. autosummary::
+   int_to_str
+   str_to_int
+```
+
+
+## Cell properties
+
+```{eval-rst}
+.. currentmodule:: h3
+
+.. autosummary::
+   get_res0_cells
+   get_pentagons
+   get_num_cells
+   get_resolution
+   get_base_cell_number
+```
+
+## Geographic coordinates
+
+Functions relating H3 objects to geographic (lat/lng) coordinates.
+
+```{eval-rst}
+.. currentmodule:: h3
+
+.. autosummary::
+   latlng_to_cell
+   cell_to_latlng
+   cell_area
+   edge_length
+   cell_to_boundary
+   directed_edge_to_boundary
+   great_circle_distance
+   average_hexagon_area
+   average_hexagon_edge_length
+```
+
+## Hierarchical relationships
+
+```{eval-rst}
+.. currentmodule:: h3
+
+.. autosummary::
+   cell_to_parent
+   cell_to_children
+   cell_to_center_child
+   compact_cells
+   uncompact_cells
+```
+
+## Cell grid relationships
+
+```{eval-rst}
+.. currentmodule:: h3
+
+.. autosummary::
+   grid_ring
+   grid_disk
+   grid_distance
+   are_neighbor_cells
+   grid_path_cells
+```
+
+## Edges
+
+```{eval-rst}
+.. currentmodule:: h3
+
+.. autosummary::
+   cells_to_directed_edge
+   get_directed_edge_destination
+   directed_edge_to_cells
+   origin_to_directed_edges
+   get_directed_edge_origin
+```
+
+## Polygon interface
+
+The ``H3Poly`` and ``H3MultiPoly`` objects and their related functions allow users to represent (multi)polygons of lat/lng points and convert back and forth between H3 cells.
+
+The objects and functions also compatible with the popular [``__geo_interface__`` protocol](https://gist.github.com/sgillies/2217756), which is used by Python geospatial libraries like [GeoPandas](https://geopandas.org/en/stable/docs/reference/api/geopandas.GeoDataFrame.__geo_interface__.html) and many plotting libraries.
+
+See the [polygon tutorial](./polygon_tutorial.ipynb) for a walkthrough.
+
+```{tip}
+As with other `h3-py` functions, the polygon interface expects coordinate pairs in **lat/lng** order.
+Note that this is reversed from [``__geo_interface__``](https://gist.github.com/sgillies/2217756) objects, which are given in **lng/lat** order.
+```
+
+### Polygon objects
+
+```{eval-rst}
+.. currentmodule:: h3
+
+.. autosummary::
+   H3Shape
+   H3Poly
+   H3MultiPoly
+```
+
+### Conversion functions
+
+```{eval-rst}
+.. currentmodule:: h3
+
+.. autosummary::
+   h3shape_to_geo
+   geo_to_h3shape
+   h3shape_to_cells
+   cells_to_h3shape
+   geo_to_cells
+   cells_to_geo
+```
+
+
+## Specialized functions
+
+### `h3-py` library
+
+```{eval-rst}
+.. currentmodule:: h3
+
+.. autosummary::
+   versions
+```
+
+### IJ-indexing
+
+```{eval-rst}
+.. currentmodule:: h3
+
+.. autosummary::
+   get_icosahedron_faces
+   cell_to_local_ij
+   local_ij_to_cell
+```
diff --git a/docs/api_reference.md b/docs/api_reference.md
diff --git a/docs/api_verbose.md b/docs/api_verbose.md
@@ -0,0 +1,10 @@
+# API Verbose Reference
+
+This page gives the full documentation for each function and object.
+Refer back to [](api_quick.md) for context and logical groupings.
+
+```{eval-rst}
+.. automodule:: h3
+    :members:
+    :imported-members:
+```
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -1,33 +1,12 @@
 # Contributing
 
-```{attention}
-This page still a work in progress.
-```
-
-## Python and Cython
-
-todo
-
-## Project organization
-
-todo
-
-## Docstring conventions
-
-https://numpydoc.readthedocs.io/en/latest/format.html
-
-## Website
-
-### TODOs
-
-- release PDF version of docs with each library verison/release?
-- page on "anatomy of an H3 index"
-
-### Other projects with nice docs
-
-For reference, here are some other projects whose docs we should
-consider when styling our own:
-
-- https://toolz.readthedocs.io/en/latest/api.html
-- http://xarray.pydata.org/
-- https://docs.dask.org/en/latest/api.html
+Contributions from the community are welcome!
+
+Please feel free to
+[file an issue](https://github.com/uber/h3-py/issues),
+open a
+[pull request](https://github.com/uber/h3-py/pulls),
+or start a
+[discussion in Github](https://github.com/uber/h3-py/discussions)
+or in the
+[H3 Slack](https://join.slack.com/t/h3-core/shared_invite/zt-g6u5r1hf-W_~uVJmfeiWtMQuBGc1NNg).
diff --git a/makefile b/makefile
@@ -21,7 +21,7 @@ clear:
 	-./env/bin/pip uninstall -y h3
 	-@rm -rf MANIFEST
 	-@rm -rf annotations
-	-@rm -rf .pytest_cache _skbuild dist .coverage build
+	-@rm -rf .pytest_cache _skbuild dist .coverage build docs/_build
 	-@find . -type d -name '__pycache__' | xargs rm -r
 	-@find . -type d -name '*.egg-info' | xargs rm -r
 	-@find . -type f -name '*.pyc' | xargs rm -r