tf2_ros is lacking Python API documentation

jo-jstrm commented 3 years ago

Problem

http://docs.ros.org/en/melodic/api/tf2_ros/html/python/ currently only contains information about exceptions, but is lacking class-member variables, functions, and function parameters. E.g. in TransformListener(), I currently cannot find out from this page what queue_size=None means and what type the param actually is.

Impact

It is very difficult to receive detailed information about tf2 functionality in python, if you use anything that is not covered in the tutorials. Therefore, tasks that can be easily performed with tf2 become tedious due to the required forum-research.

Proposed Solution

Add documentation details for tf2_ros. Can I help in any way here?

tfoote commented 3 years ago

It would be great to fill in more documentation. It's hosted in the doc subdirectory. In particular here is what you're mentioning: https://github.com/ros/geometry2/blob/noetic-devel/tf2_ros/doc/tf2_ros.rst

jo-jstrm commented 3 years ago

Turns out the documentation for Buffer, TransformListener etc. already exists in the source files. I cloned the geometry2 repo and ran sphinx-build -b html locally, which resulted in i) the same html files as online (i.e. some exceptions are documented, but the other classes, such as Buffer, not) and ii) the following errors that correspond to the undocumented classes. Therefore, those errors seem to be the root of the lack of documentation online. Currently I am not able to resolve them, so I would be glad for any suggestions.

I am on elementary OS 5.1 (Ubuntu 18.04) with ROS Melodic installed.

Running Sphinx v1.6.7
WARNING: sphinx.ext.pngmath has been deprecated. Please use sphinx.ext.imgmath instead.
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 2 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] tf2_ros                                                                                                                                                                   
/home/jo/git/geometry2/tf2_ros/doc/tf2_ros.rst:44: WARNING: autodoc: failed to import exception 'TypeException' from module 'tf2_ros.buffer_interface'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/ext/autodoc.py", line 658, in import_object
    __import__(self.modname)
  File "/opt/ros/melodic/lib/python2.7/dist-packages/tf2_ros/__init__.py", line 38, in <module>
    from tf2_py import *
  File "/opt/ros/melodic/lib/python2.7/dist-packages/tf2_py/__init__.py", line 38, in <module>
    from ._tf2 import *
ImportError: dynamic module does not define module export function (PyInit__tf2)
/home/jo/git/geometry2/tf2_ros/doc/tf2_ros.rst:46: WARNING: autodoc: failed to import exception 'NotImplementedException' from module 'tf2_ros.buffer_interface'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/ext/autodoc.py", line 658, in import_object
    __import__(self.modname)
  File "/opt/ros/melodic/lib/python2.7/dist-packages/tf2_ros/__init__.py", line 38, in <module>
    from tf2_py import *
  File "/opt/ros/melodic/lib/python2.7/dist-packages/tf2_py/__init__.py", line 38, in <module>
    from ._tf2 import *
ImportError: dynamic module does not define module export function (PyInit__tf2)
/home/jo/git/geometry2/tf2_ros/doc/tf2_ros.rst:51: WARNING: autodoc: failed to import class 'BufferInterface' from module 'tf2_ros.buffer_interface'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/ext/autodoc.py", line 658, in import_object
    __import__(self.modname)
  File "/opt/ros/melodic/lib/python2.7/dist-packages/tf2_ros/__init__.py", line 38, in <module>
    from tf2_py import *
  File "/opt/ros/melodic/lib/python2.7/dist-packages/tf2_py/__init__.py", line 38, in <module>
    from ._tf2 import *
ImportError: dynamic module does not define module export function (PyInit__tf2)
/home/jo/git/geometry2/tf2_ros/doc/tf2_ros.rst:56: WARNING: autodoc: failed to import class 'Buffer' from module 'tf2_ros.buffer'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/ext/autodoc.py", line 658, in import_object
    __import__(self.modname)
  File "/opt/ros/melodic/lib/python2.7/dist-packages/tf2_ros/__init__.py", line 38, in <module>
    from tf2_py import *
  File "/opt/ros/melodic/lib/python2.7/dist-packages/tf2_py/__init__.py", line 38, in <module>
    from ._tf2 import *
ImportError: dynamic module does not define module export function (PyInit__tf2)
/home/jo/git/geometry2/tf2_ros/doc/tf2_ros.rst:61: WARNING: autodoc: failed to import class 'BufferClient' from module 'tf2_ros.buffer_client'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/ext/autodoc.py", line 658, in import_object
    __import__(self.modname)
  File "/opt/ros/melodic/lib/python2.7/dist-packages/tf2_ros/__init__.py", line 38, in <module>
    from tf2_py import *
  File "/opt/ros/melodic/lib/python2.7/dist-packages/tf2_py/__init__.py", line 38, in <module>
    from ._tf2 import *
ImportError: dynamic module does not define module export function (PyInit__tf2)
/home/jo/git/geometry2/tf2_ros/doc/tf2_ros.rst:67: WARNING: autodoc: failed to import class 'TransformBroadcaster' from module 'tf2_ros.transform_broadcaster'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/ext/autodoc.py", line 658, in import_object
    __import__(self.modname)
  File "/opt/ros/melodic/lib/python2.7/dist-packages/tf2_ros/__init__.py", line 38, in <module>
    from tf2_py import *
  File "/opt/ros/melodic/lib/python2.7/dist-packages/tf2_py/__init__.py", line 38, in <module>
    from ._tf2 import *
ImportError: dynamic module does not define module export function (PyInit__tf2)
/home/jo/git/geometry2/tf2_ros/doc/tf2_ros.rst:72: WARNING: autodoc: failed to import class 'TransformListener' from module 'tf2_ros.transform_listener'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/ext/autodoc.py", line 658, in import_object
    __import__(self.modname)
  File "/opt/ros/melodic/lib/python2.7/dist-packages/tf2_ros/__init__.py", line 38, in <module>
    from tf2_py import *
  File "/opt/ros/melodic/lib/python2.7/dist-packages/tf2_py/__init__.py", line 38, in <module>
    from ._tf2 import *
ImportError: dynamic module does not define module export function (PyInit__tf2)
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] tf2_ros                                                                                                                                                                    
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 8 warnings.

tfoote commented 3 years ago

There may be an issue that _tf2 needs to be built. It's a c binding for python from tf2_py.

jo-jstrm commented 3 years ago

Sorry for the long delay. Turns out the issue above was related to "Python3 vs Pyhton2" issues. After sorting that out, I got the following error:

Sphinx v1.8.5 in Verwendung

Extension error:
Could not import extension sphinx.ext.pngmath (exception: No module named pngmath)

Using a Pyhton2 environment with sphinx-build 1.8.5 and ros-melodic installed, I had to replace sphinx.ext.pngmath with sphinx.ext.imgmath in docs/conf.py. With that change I successfully build the complete docs. The docs now contain all documentation for BufferInterface, Buffer, BufferClient, TransformBroadcaster, and TransformListener.

However, because I do not know the exact build pipeline/system for the website, I think I can not help any further than that. Maybe the issue is only sphinx.ext.pngmath, maybe it has also something to do with Python2 vs. 3.

jonatanolofsson commented 3 years ago

Is there any way we can add priority to this? It is sorely needed - and quite frankly embarassing for a project of this dignity (no offense)

MatthijsBurgh commented 3 years ago

Lets also get the python docs up for noetic, there is not even a page there.

MatthijsBurgh commented 2 years ago

This is partly fixed by #521. As now the documentation is generated, but it still has trouble importing tf2_py. As the cpp module is not build. So it can't be imported. (See https://github.com/ros/geometry2/issues/340). For noetic log see: https://build.ros.org/job/Ndoc__geometry2__ubuntu_focal_amd64/lastBuild/console#console-section-5

tronje commented 1 year ago

Is there any progress on this? When I try to access e.g. http://docs.ros.org/en/noetic/api/tf2_geometry_msgs/html/python I get a 404 error.

The docs at http://docs.ros.org/en/noetic/api/tf2_ros/html/python/ exist, but they may as well return 404 as well for all the information they provide.

ros / geometry2