Python API Documentation?

[Harry]

Is there some centralized location that I can find API documentation for the Python GTSAM wrapper? I've encountered issues where some factors or other GTSAM objects that are available in the C++ API are not present in the Python wrapper (running the latest develop branch). Does a centralized documentation source exist that shows what parts of the GTSAM API are fully supported in the Python wrapper vs what parts are not or still to-do?

Thanks!

[Dellaert, Frank]

Hi, no, unfortunately we could never find someone who really *killed* our “readthedocs” project. That means currently the .i files a+ c++ docs is your only guidance (although you can do “help” on any function in python).

 

Let me know if you’re interested in helping out with the docs.

 

Frank

 

--
You received this message because you are subscribed to the Google Groups "gtsam users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to gtsam-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/gtsam-users/3532b19e-7f30-4c77-a6b8-09e6898d7c02n%40googlegroups.com.

[Joel Truher]

i'm definitely interested in documentation; my students won't be able to guess at the python API by reading the C++ code.

i stumbled across ProfFan/gtsam-stubs which seems like a step in the right direction, though it looks like it's made by hand?

is it possible to generate untyped stubs as part of the "wrap" process?

[Joel Truher]

Also if I'm reading it right, it looks like there's C++ stuff that's just not included in python, for example, slam.i references BetweenFactor but not BoundingConstraint.  is that on purpose, or would it be ok to add more coverage?

actually come to think of it i can't find the specialization that tells python about the name BetweenFactorPose2, so i'm not doing great navigating the api either.

[Dellaert, Frank]

You’re bringing up an amazing point and a sour point since a long time. I’ve been wanting someone to take up two related projects for a while:

1. a great readthedocs site 
   
2. automatically generated python documentation
   

Seems that especially 2 would be very helpful for your students. If you’re willing to help with that, maybe you and I could have a meeting about it :-)

Best!

Frank

---

From: gtsam...@googlegroups.com <gtsam...@googlegroups.com> on behalf of Joel Truher <joel....@gmail.com>
Sent: Friday, August 16, 2024 9:14:05 AM
To: gtsam users <gtsam...@googlegroups.com>
Subject: Re: [GTSAM] Python API Documentation?

 

You don't often get email from joel....@gmail.com. Learn why this is important

To view this discussion on the web visit https://groups.google.com/d/msgid/gtsam-users/b3ad7ef0-b415-46e0-83cd-2de6a6844434n%40googlegroups.com.

[Joel Truher]

gtsam builds fine on my box, let me see if i can add #2 to the build.

[Jiang, Fan]

Hi Joel,

#2 is not that easy, since most of the docs are actually in C++ as Doxygen comments. In the past I have some ideas about using Clang to automatically parse and generate, but never got the bandwidth. There may also be some new open-source tools that allow you to do this automatically, last time I checked was 2022.

After you parse the C++ headers, you still need automated translation from Doxygen to sphinx format, which I don’t know if there are pre-built tools for.

On the type stubs, they are mostly generated with `stubgen` but I have some manual patches to make it work. For type checks they work pretty well.

Best,

Fan

Fan Jiang

5th year Robotics PhD
Georgia Institute of Technology

E-mail: fan....@gatech.edu

Try TeXmacs today!

On Aug 16, 2024, at 13:34, Joel Truher <jo...@truher.org> wrote:

You don't often get email from jo...@truher.org. Learn why this is important

To view this discussion on the web visit https://groups.google.com/d/msgid/gtsam-users/CADp_5xL%2Bw-_18H7xq-7TaQOY%3DZ2MZVtq0%3DV6uqhMY58k405tBw%40mail.gmail.com.

[Joel Truher]

cool, thanks, i really appreciate the enthusiasm from all of you.

re: stubs, i don't really need the docs, i just want python autocomplete to work in vscode, which i why i thought it might be not-too-hard for me to figure out.

re: wrapping, yeah, i see now.  the particular example i was working through was the BoundingConstraint, which works via its virtual value() function, and i guess you could use PYBIND11_OVERRIDE for that sort of thing.  it doesn't look like you use this pattern *that* often, so it wouldn't be *that* bad to sprinkle some of those macros around.  :-)

On Fri, Aug 16, 2024 at 11:01 AM Varun Agrawal <varag...@gmail.com> wrote:

Couple of things I wanted to add:

1. Fan is correct that auto-parsing docs is hard. If we can get the ReadTheDocs going for the C++ code, the documentation should be the same for both C++ and Python versions of the code with just language specific differences.

2. Lots of functionality is still not wrapped due to various reasons, most of them being support from Pybind11. If you have specific needs, I am happy to wrap them for you. :)

3. I had made a PR on the wrap project for autogenerating stubs which actually worked quite well. Fan pushed back on it at the time for a reason I don't recall and I trust his judgement on these things which is why I haven't pursued it. Perhaps we should revisit that.

To view this discussion on the web visit https://groups.google.com/d/msgid/gtsam-users/D6E0BDA4-BC00-4108-9E8D-988846CC0752%40gatech.edu.

[Jiang, Fan]

Hi Joel,

You can use the `gtsam-stubs` repo for a temporary solution. For future, we can revisit the stub generator Varun mentioned (I don’t remember which PR is that).

re. BoundingConstraint and classes you want to OVERRIDE from Python: they can be implemented within https://github.com/borglab/gtsam/tree/develop/python/gtsam/specializations using C++. I actually do not know why BoundingConstraint even require virtual and overriding and not just storing the value.

Best,

Fan

Fan Jiang

5th year Robotics PhD
Georgia Institute of Technology

E-mail: fan....@gatech.edu

Try TeXmacs today!

[Joel Truher]

cool vscode can use gtsam-stubs for autocomplete, works great.  thanks!

i confess that i don't understand what is going on with that specializations directory at all.  it's ok for now, the things i'm doing are simple enough to work as CustomFactors.

To view this discussion on the web visit https://groups.google.com/d/msgid/gtsam-users/7019D64D-7264-4122-B925-83EE7735E78F%40gatech.edu.

[Varun Agrawal]

Couple of things I wanted to add:

1. Fan is correct that auto-parsing docs is hard. If we can get the ReadTheDocs going for the C++ code, the documentation should be the same for both C++ and Python versions of the code with just language specific differences.

2. Lots of functionality is still not wrapped due to various reasons, most of them being support from Pybind11. If you have specific needs, I am happy to wrap them for you. :)

3. I had made a PR on the wrap project for autogenerating stubs which actually worked quite well. Fan pushed back on it at the time for a reason I don't recall and I trust his judgement on these things which is why I haven't pursued it. Perhaps we should revisit that.

On Fri, Aug 16, 2024, 1:43 PM Jiang, Fan <fan....@gatech.edu> wrote:

To view this discussion on the web visit https://groups.google.com/d/msgid/gtsam-users/D6E0BDA4-BC00-4108-9E8D-988846CC0752%40gatech.edu.