DOC: API reference tweaks & clean-up (#89)

* sphinx conf: remove invalid options

* disable pybind11 generated docstring signatures

Add them manually instead, without type hints. It is a bit more tedious
to maintain but the result is more consistent and readable.

- Pybind11 type hints not always reliable (e.g., non-vectorized
arguments of py::vectorize functions show as numpy.ndarray, too generic
return type)

- didn't work with sphinx's ``autodoc_typehints = "none"``, which seemed
to be ignored for some reason. Adding type hints in the function
signatures in the API documentation makes those signature less readable
and doesn't add much information (type hints already in the parameter
and return description sections)

Also add "Returns" sections in docstrings more globally.

* fix get_dimensions()

Return values that are consistent with shapely for collections.

* add more Returns sections in docstrings

* add docstrings for Projection static methods

Also move Projection to api-hidden.

* GeographyType: add docstrings and tests

* Use "geography" as name for single arg functions

Also move get_x and get_y functions to geography.cpp (geography
properties).

* doc API: add description for each subsection

* add (py)arrow to intersphinx

* review comments

* 1-arg vectorized funcs: pos only

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

@@ -24,18 +24,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"]

src/accessors-geog.cpp

@@ -26,22 +26,6 @@ PyObjectGeography convex_hull(PyObjectGeography a) {
     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 @@ void init_accessors(py::module& m) {
 
     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 @@ void init_accessors(py::module& m) {
           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");
 }