gdal
gdal copied to clipboard
OSGeo
DOC: Fix python OGR/GDAL docstrings
flake8 failure is unrelated:
autotest/osr/osr_ct.py:35:1: F401 'sys' imported but unused
How do the changes in swig/include/python/docs/ have been done ? Those are generated files...
How do the changes in swig/include/python/docs/ have been done ? Those are generated files...
Oof, I missed the README. I have been making the changes manually :man_facepalming:
I am wondering if now would be a good time to separate the C/CPP docstrings from the Python docstrings? I think at this stage, any new Python docs can be added incrementally and should not produce much overhead to add manually. Additionally, with the Python API docs being generated by sphinx, the docs will be able to provide a direct link to the parent C/CPP documentation that has more details. This will enable making the Python docstrings more useful for Python programmers and reference the Python types and tips for how to handle things in python versus the C/CPP types.
For example, the Python API docs could start to look like this:
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.
I am wondering if now would be a good time to separate the C/CPP docstrings from the Python docstrings?
I'm a bit 50% 50% on this. There's the precedent of swig/java/javadoc.java, which is a custom thing putting the Javadocs of the mapped methods, derived from the original C++ docs, in a sort of .java file post-processed by an ad-hoc script to reinject the content in the real bindings .java file, that I initiated looong time ago but have totally neglected updating
I'm a bit 50% 50% on this.
There were quite a few tweaks necessary to get the docs to work with sphinx and be formatted properly. I haven't dug into it, but probably would require some updates to the C/CPP docstrings to standardize some things to be able to fully automate it.
have totally neglected updating
That is a real possibility for the Python API docs if it is disconnected. Adding - [ ] Updated Python API docs to the PR template may help?
Adding
- [ ] Updated Python API docsto the PR template may help?
yes, will just require I read it myself :-)
An automated option could be to use pylint to check if the docstrings are missing or not:
demo.py
def func_no_docstring():
return None
python -m pylint demo.py
************* Module demo
demo.py:1:0: C0114: Missing module docstring (missing-module-docstring)
demo.py:1:0: C0116: Missing function or method docstring (missing-function-docstring)
-----------------------------------
Your code has been rated at 0.00/10
anything you wanted to add to this PR, or is it good for merge ?
Feel free to merge. There are other fixes that may be good to add, but I think doing it incrementally is a good idea to prevent it from getting out of sync with other changes.
but I think doing it incrementally is a good idea to prevent it from getting out of sync with other changes.
ok, but the REGENERATE_PYTHON_DOCS logic in swig/python/CMakeLists.txt should be removed soon, otherwise there's the risk of your manual overrides to be lost
the REGENERATE_PYTHON_DOCS logic in swig/python/CMakeLists.txt should be removed soon
That is a good call. Created: https://github.com/OSGeo/gdal/issues/6187