DOC: API reference tweaks & clean-up

docs/api.rst

@@ -10,6 +10,9 @@ API reference
 Geography properties
 --------------------
 
+Functions that provide access to properties of :py:class:`~spherely.Geography`
+objects without side-effects (except for ``prepare`` and ``destroy_prepared``).
+
 .. autosummary::
    :toctree: _api_generated/
 
@@ -28,6 +31,9 @@ Geography properties
 Geography creation
 ------------------
 
+Functions that build new :py:class:`~spherely.Geography` objects from
+coordinates or existing geographies.
+
 .. autosummary::
    :toctree: _api_generated/
 
@@ -44,6 +50,9 @@ Geography creation
 Input/Output
 ------------
 
+Functions that convert :py:class:`~spherely.Geography` objects to/from an
+external format such as `WKT <https://en.wikipedia.org/wiki/Well-known_text>`_.
+
 .. autosummary::
    :toctree: _api_generated/
 
@@ -53,13 +62,14 @@ Input/Output
    to_wkb
    from_geoarrow
    to_geoarrow
-   Projection
 
 .. _api_measurement:
 
 Measurement
 -----------
 
+Functions that compute measurements of one or more geographies.
+
 .. autosummary::
    :toctree: _api_generated/
 
@@ -73,6 +83,9 @@ Measurement
 Predicates
 ----------
 
+Functions that return ``True`` or ``False`` for some spatial relationship
+between two geographies.
+
 .. autosummary::
    :toctree: _api_generated/
 
@@ -90,6 +103,9 @@ Predicates
 Overlays (boolean operations)
 -----------------------------
 
+Functions that generate a new geography based on the combination of two
+geographies.
+
 .. autosummary::
    :toctree: _api_generated/
 
@@ -103,6 +119,8 @@ Overlays (boolean operations)
 Constructive operations
 -----------------------
 
+Functions that generate a new geography based on input.
+
 .. autosummary::
    :toctree: _api_generated/
 

docs/api_hidden.rst

@@ -8,3 +8,7 @@
    Geography
    Geography.dimensions
    Geography.nshape
+   Projection
+   Projection.lnglat
+   Projection.pseudo_mercator
+   Projection.orthographic

docs/conf.py

@@ -18,18 +18,26 @@
     "python": ("https://docs.python.org/3", None),
     "numpy": ("https://numpy.org/doc/stable", None),
     "shapely": ("https://shapely.readthedocs.io/en/latest/", None),
+    "pyarrow": ("https://arrow.apache.org/docs/", None),
 }
 
-autodoc_typehints = "none"
-
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
 napoleon_use_param = False
 napoleon_use_rtype = False
 napoleon_preprocess_types = True
 napoleon_type_aliases = {
+    # general terms
+    "sequence": ":term:`sequence`",
+    "iterable": ":term:`iterable`",
+    # numpy terms
     "array_like": ":term:`array_like`",
     "array-like": ":term:`array-like <array_like>`",
+    # objects without namespace: spherely
+    "EARTH_RADIUS_METERS": "spherely.EARTH_RADIUS_METERS",
+    # objects without namespace: numpy
+    "ndarray": "~numpy.ndarray",
+    "array": ":term:`array`",
 }
 
 # source_suffix = ['.rst', '.md']
@@ -61,8 +69,6 @@
     use_repository_button=True,
     use_issues_button=True,
     home_page_in_toc=False,
-    extra_navbar="",
-    navbar_footer_text="",
 )
 
 html_static_path = ["_static"]

src/accessors-geog.cpp

@@ -26,22 +26,6 @@
     return make_py_geography(s2geog::s2_convex_hull(a_ptr));
 }
 
-double get_x(PyObjectGeography a) {
-    auto geog = a.as_geog_ptr();
-    if (geog->geog_type() != GeographyType::Point) {
-        throw py::value_error("Only Point geometries supported");
-    }
-    return s2geog::s2_x(geog->geog());
-}
-
-double get_y(PyObjectGeography a) {
-    auto geog = a.as_geog_ptr();
-    if (geog->geog_type() != GeographyType::Point) {
-        throw py::value_error("Only Point geometries supported");
-    }
-    return s2geog::s2_y(geog->geog());
-}
-
 double distance(PyObjectGeography a,
                 PyObjectGeography b,
                 double radius = numeric_constants::EARTH_RADIUS_METERS) {
@@ -67,66 +51,62 @@
 
     m.def("centroid",
           py::vectorize(&centroid),
-          py::arg("a"),
-          R"pbdoc(
+          py::arg("geography"),
+          py::pos_only(),
+          R"pbdoc(centroid(geography, /)
+
         Computes the centroid of each geography.
 
         Parameters
         ----------
-        a : :py:class:`Geography` or array_like
-            Geography object
+        geography : :py:class:`Geography` or array_like
+            Geography object(s).
+
+        Returns
+        -------
+        Geography or array
+            A single or an array of POINT Geography object(s).
 
     )pbdoc");
 
     m.def("boundary",
           py::vectorize(&boundary),
-          py::arg("a"),
-          R"pbdoc(
+          py::arg("geography"),
+          py::pos_only(),
+          R"pbdoc(boundary(geography, /)
+
         Computes the boundary of each geography.
 
         Parameters
         ----------
-        a : :py:class:`Geography` or array_like
-            Geography object
+        geography : :py:class:`Geography` or array_like
+            Geography object(s).
+
+        Returns
+        -------
+        Geography or array
+            A single or an array of either (MULTI)POINT or (MULTI)LINESTRING
+            Geography object(s).
 
     )pbdoc");
 
     m.def("convex_hull",
           py::vectorize(&convex_hull),
-          py::arg("a"),
-          R"pbdoc(
-        Computes the convex hull of each geography.
+          py::arg("geography"),
+          py::pos_only(),
+          R"pbdoc(convex_hull(geography, /)
 
-        Parameters
-        ----------
-        a : :py:class:`Geography` or array_like
-            Geography object
-
-    )pbdoc");
-
-    m.def("get_x",
-          py::vectorize(&get_x),
-          py::arg("a"),
-          R"pbdoc(
-        Returns the longitude value of the Point (in degrees).
+        Computes the convex hull of each geography.
 
         Parameters
         ----------
-        a: :py:class:`Geography` or array_like
+        geography : :py:class:`Geography` or array_like
             Geography object(s).
 
-    )pbdoc");
-
-    m.def("get_y",
-          py::vectorize(&get_y),
-          py::arg("a"),
-          R"pbdoc(
-        Returns the latitude value of the Point (in degrees).
-
-        Parameters
-        ----------
-        a: :py:class:`Geography` or array_like
-            Geography object(s).
+        Returns
+        -------
+        Geography or array
+            A single or an array of POLYGON Geography object(s).
 
     )pbdoc");
 
@@ -135,64 +115,92 @@
           py::arg("a"),
           py::arg("b"),
           py::arg("radius") = numeric_constants::EARTH_RADIUS_METERS,
-          R"pbdoc(
+          R"pbdoc(distance(a, b, radius=spherely.EARTH_RADIUS_METERS)
+
         Calculate the distance between two geographies.
 
         Parameters
         ----------
         a : :py:class:`Geography` or array_like
-            Geography object
+            Geography object(s).
         b : :py:class:`Geography` or array_like
-            Geography object
+            Geography object(s).
         radius : float, optional
-            Radius of Earth in meters, default 6,371,010
+            Radius of Earth in meters, default 6,371,010.
+
+        Returns
+        -------
+        float or array
+            Distance value(s), in meters.
 
     )pbdoc");
 
     m.def("area",
           py::vectorize(&area),
-          py::arg("a"),
+          py::arg("geography"),
+          py::pos_only(),
           py::arg("radius") = numeric_constants::EARTH_RADIUS_METERS,
-          R"pbdoc(
+          R"pbdoc(area(geography, /, radius=spherely.EARTH_RADIUS_METERS)
+
         Calculate the area of the geography.
 
         Parameters
         ----------
-        a : :py:class:`Geography` or array_like
-            Geography object
+        geography : :py:class:`Geography` or array_like
+            Geography object(s).
         radius : float, optional
-            Radius of Earth in meters, default 6,371,010
+            Radius of Earth in meters, default 6,371,010.
+
+        Returns
+        -------
+        float or array
+            Area value(s), in square meters.
 
     )pbdoc");
 
     m.def("length",
           py::vectorize(&length),
-          py::arg("a"),
+          py::arg("geography"),
+          py::pos_only(),
           py::arg("radius") = numeric_constants::EARTH_RADIUS_METERS,
-          R"pbdoc(
+          R"pbdoc(length(geography, /, radius=spherely.EARTH_RADIUS_METERS)
+
         Calculates the length of a line geography, returning zero for other types.
 
         Parameters
         ----------
-        a : :py:class:`Geography` or array_like
-            Geography object
+        geography : :py:class:`Geography` or array_like
+            Geography object(s).
         radius : float, optional
-            Radius of Earth in meters, default 6,371,010
+            Radius of Earth in meters, default 6,371,010.
+
+        Returns
+        -------
+        float or array
+            Length value(s), in meters.
 
    )pbdoc");
 
     m.def("perimeter",
           py::vectorize(&perimeter),
-          py::arg("a"),
+          py::arg("geography"),
+          py::pos_only(),
           py::arg("radius") = numeric_constants::EARTH_RADIUS_METERS,
-          R"pbdoc(
+          R"pbdoc(perimeter(geography, /, radius=spherely.EARTH_RADIUS_METERS)
+
         Calculates the perimeter of a polygon geography, returning zero for other types.
 
         Parameters
         ----------
-        a : :py:class:`Geography` or array_like
-            Geography object
+        geography : :py:class:`Geography` or array_like
+            Geography object(s).
         radius : float, optional
-            Radius of Earth in meters, default 6,371,010
+            Radius of Earth in meters, default 6,371,010.
+
+        Returns
+        -------
+        float or array
+            Perimeter value(s), in meters.
+
     )pbdoc");
 }