DOC: Python API docstrings layout

[snowman2]

Here is an example of what I am thinking for the layout of the docstrings:

Determines whether two geometries intersect.

For more details: :cpp:func:`OGR_G_Intersects`

Parameters
-----------
hGeom: Geometry
    The first geometry.
hOtherGeom: Geometry
    The other geometry to test against.

Returns
--------
int:
    True if the geometries intersect, otherwise False.

The goal of this layout is to keep the Python docstrings simple yet useful.

It contains:

• A brief description of what the function does
• A reference to the C/CPP function it calls (has more details of behavior, etc, ...)
• Python types referenced in the docstrings (helps navigate which types are needed)

Thoughts?

[rouault]

Thoughts?

LGTM. (Is there a standard way for Python doc, similar to Doxygen for C/C++, to document parameters and return values ? I somehow remember the answer is "not really")

[snowman2]

Is there a standard way for Python doc, similar to Doxygen for C/C++, to document parameters and return values ?

numpydoc is what I recommend: https://numpydoc.readthedocs.io/en/latest/format.html

• pyproj
• xarray
• pandas

[snowman2]

If type hints are added, this could be useful: https://github.com/tox-dev/sphinx-autodoc-typehints

[dbaston]

I've added many of these docstrings and referenced the NumPy guidelines in https://gdal.org/development/dev_documentation.html#python-api-documentation