search

OSGeo / gdal

GDAL is an open source MIT licensed translator library for raster and vector geospatial data formats.
https://gdal.org
Other
4.91k stars 2.56k forks source link

DOC: intersphinx for python API #6132

Closed snowman2 closed 2 years ago

snowman2 commented 2 years ago

https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

It seems to work for the C/CPP functions, but not for Python.

rouault commented 2 years ago

can you explicit what you've in mind with this ticket ?

snowman2 commented 2 years ago

I should have provided some more context initially. I ran into this when working on https://github.com/rasterio/rasterio/pull/2537.

If I download https://gdal.org/objects.inv, and use https://sphobjinv.readthedocs.io/en/latest/index.html to convert to json (sphobjinv convert json objects.inv), I can find:

{"name": "GDALCreateRPCTransformerV2", "domain": "cpp", "role": "function", "priority": "1", "uri": "api/gdal_alg.html#_CPPv426GDALCreateRPCTransformerV2PK13GDALRPCInfoV2idPPc", "dispname": "-"}

However, I cannot find UseExceptions or any other python functions indexed. This means I cannot use intersphinx to automatically link to the gdal Python API documentation. I am assuming this is because sphinx is not used to generate the Python API documentation?

rouault commented 2 years ago

I am assuming this is because sphinx is not used to generate the Python API documentation?

yes, the Python API doc is really scarce (due to SWIG not really supporting that), and using epydoc: https://github.com/OSGeo/gdal/blob/130bc9862e4080750be953d026f7ddbf9e81ddc3/swig/python/CMakeLists.txt#L463

snowman2 commented 2 years ago

I wonder if https://github.com/sphinx-contrib/apidoc would be any help?

rouault commented 2 years ago

I wonder if https://github.com/sphinx-contrib/apidoc would be any help?

not sure: the root issue is that it is not easy to associate Python docstrings with bindings generated by SWIG

snowman2 commented 2 years ago

Not sure if you're interested or not, but I gave it a try in #6137.

bskinn commented 2 years ago

Does SWIG produce any sort of structured output surrounding the Python functions? If so, it should be possible to use sphobjinv's API either to augment the objects.inv with the C/CPP objects to also contain the Python ones, or to create an auxiliary objects.inv with just the Python items.