Cli tools documentation #653

CursedRock17 · 2024-02-20T00:58:26Z

This Pull Request is a direct link to issue #550 which looks to improve documentation, specifically in CLI commands like tf2_echo. In this PR, all tools and documentation related to tf2_ros are put in one central place, hopefully https://docs.ros.org/.

Signed-off-by: CursedRock17 <[email protected]>

tfoote

I tried running this with rosdoc2 and I don't think that these are being picked up by sphinx in ROS 2 and rendered. I think this will need a rosdoc2.yaml config setup to pick up these resources.

tfoote · 2024-02-21T23:40:34Z

tf2_ros/docs/source/index.rst

- Pass the :class:`tf2_ros.Buffer` to the constructor of :class:`tf2_ros.TransformListener`.
-    - Optionally, pass a :class:`ros.NodeHandle` (otherwise TransformListener will connect to the node for the process).
-    - Optionally, specify if the TransformListener runs in its own thread or not.
+  * **tf2_ros::Buffer::transform** is the main method for applying transforms.


Do these still create links to the Doxygen content?

Right now the loacl links are done through rst which puts them next to what we're trying to list. I assumed this would be the easiest thing to do when it came to overall documentation.
Here's a video of what it should look like:

Geometry2_Docs.mov

To recreate do the following in the terminal

Clone the repo

cd tf2_ros/docs

make html

rosdoc2 build --package-path ./..

rosdoc2 open ./docs_output/tf2_ros/index.html

Run it on the web so something like python3 -m http.server will work for localhost

Are packages like rosdoc2, exhale, and breathe able to run on the docs, or is this overengineered?

Signed-off-by: CursedRock17 <[email protected]>

CursedRock17 · 2024-02-22T04:34:52Z

I've recreated the rosdoc.yaml file in rosdoc2 terms so doxygen and sphinx content should be put out into the same file. As for the Links to the Doxygen content I have to rewrite those to be locally linked

tf2_ros/docs/source/cli_tools.rst

tf2_ros/docs/source/index.rst

Signed-off-by: CursedRock17 <[email protected]>

tf2_ros/docs/source/cli_tools.rst

Signed-off-by: CursedRock17 <[email protected]>

ros-discourse · 2024-04-07T04:43:44Z

This pull request has been mentioned on ROS Discourse. There might be relevant details there:

https://discourse.ros.org/t/nomenclature-of-tf-echo-and-tf-listener/36985/6

ahcorde · 2024-04-19T12:46:10Z

I made here some suggestions CursedRock17#1

Signed-off-by: CursedRock17 <[email protected]> Removing exhale Signed-off-by: CursedRock17 <[email protected]> Fixing doxyfile Signed-off-by: CursedRock17 <[email protected]> Removing extra picture Signed-off-by: CursedRock17 <[email protected]>

Signed-off-by: CursedRock17 <[email protected]>

CursedRock17 · 2024-04-21T20:55:58Z

I went ahead and added those changes you suggested, along with getting the Sphinx and Doxygen docs working for both python and C++

ahcorde

I can see these errors:

/home/ahcorde/ros2_rolling/src/ros2/geometry2/tf2_ros/doc/index.rst:8: WARNING: undefined label: 'exhale_class_classtf2__ros_1_1_transform_broadcaster'
/home/ahcorde/ros2_rolling/src/ros2/geometry2/tf2_ros/doc/index.rst:14: WARNING: undefined label: 'exhale_class_classtf2__ros_1_1_static_transform_broadcaster'
/home/ahcorde/ros2_rolling/src/ros2/geometry2/tf2_ros/doc/index.rst:20: WARNING: undefined label: 'exhale_class_classtf2__ros_1_1_buffer'
/home/ahcorde/ros2_rolling/src/ros2/geometry2/tf2_ros/doc/index.rst:20: WARNING: undefined label: 'exhale_class_classtf2__ros_1_1_buffer_interface'
/home/ahcorde/ros2_rolling/src/ros2/geometry2/tf2_ros/doc/index.rst:20: WARNING: undefined label: 'exhale_class_classtf2__ros_1_1_transform_listener'
/home/ahcorde/ros2_rolling/src/ros2/geometry2/tf2_ros/doc/index.rst:32: WARNING: undefined label: 'exhale_class_classtf2__ros_1_1_message_filter'

ahcorde · 2024-04-19T12:21:06Z

tf2_ros/docs/source/tf2_ros2.rst

@@ -39,7 +39,7 @@ Exceptions
 .. exception:: tf2.InvalidArgumentException

   subclass of :exc:`TransformException`.
-   Raised when the arguments to the method are called improperly formed.  An example of why this might be raised is if an argument is nan. 
+   Raised when the arguments to the method are called improperly formed.  An example of why this might be raised is if an argument is nan.


Suggested change

Raised when the arguments to the method are called improperly formed. An example of why this might be raised is if an argument is nan.

Raised when the arguments to the method are called improperly formed. An example of why this might be raised is if an argument is nan.

ahcorde · 2024-05-20T13:12:03Z

tf2_ros/doc/cli_tools.rst

+
+  ros2 run turtlesim turtle_teleop_key
+
+Now using tf2_echo to take a look at the different transformations occuring between two frames


Suggested change

Now using tf2_echo to take a look at the different transformations occuring between two frames

Now using tf2_echo to take a look at the different transformations occurring between two frames

ahcorde · 2024-05-20T13:12:36Z

tf2_ros/doc/cli_tools.rst

+
+1. tf2_echo
+^^^^^^^^^^^
+tf2_echo is the simplest tool to look at the numeric values of a specific transform. tf2_echo takes two arguments: the source frame and the target frame. The output of tf2_echo is the target frame in comparison to the source frame. E.g. to get the transformation from turtle1 to turtle2, set up the turtlesim example with:


Suggested change

tf2_echo is the simplest tool to look at the numeric values of a specific transform. tf2_echo takes two arguments: the source frame and the target frame. The output of tf2_echo is the target frame in comparison to the source frame. E.g. to get the transformation from turtle1 to turtle2, set up the turtlesim example with:

``tf2_echo`` is the simplest tool to look at the numeric values of a specific transform. ``tf2_echo`` takes two arguments: the source frame and the target frame. The output of ``tf2_echo`` is the target frame in comparison to the source frame. E.g. to get the transformation from turtle1 to turtle2, set up the turtlesim example with:

ahcorde · 2024-05-20T13:12:59Z

tf2_ros/doc/cli_tools.rst

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`rqt_tf_tree <https://github.com/ros-visualization/rqt_tf_tree/tree/master>`_  provides a GUI to inspect tf tree during runtime.
+
+  A simple tree from the tutorial in 1. tf2_echo looks like:


Suggested change

A simple tree from the tutorial in 1. tf2_echo looks like:

A simple tree from the tutorial in 1. ``tf2_echo`` looks like:

ahcorde · 2024-05-20T13:13:07Z

tf2_ros/doc/cli_tools.rst

+
+2. tf2_monitor
+^^^^^^^^^^^^^^
+tf2_monitor can give you a lot of detailed information about a specific transformation you care about. The monitor will break down the chain between two frames into individual transforms, and provide statistics about timing, broadcasters, etc.


Suggested change

tf2_monitor can give you a lot of detailed information about a specific transformation you care about. The monitor will break down the chain between two frames into individual transforms, and provide statistics about timing, broadcasters, etc.

``tf2_monitor`` can give you a lot of detailed information about a specific transformation you care about. The monitor will break down the chain between two frames into individual transforms, and provide statistics about timing, broadcasters, etc.

ahcorde · 2024-05-20T13:13:38Z

tf2_ros/doc/cli_tools.rst

+
+  ros2 run tf2_ros static_transform_publisher [--x X] [--y Y] [--z Z] [--yaw Yaw] [--pitch Pitch] [--roll Roll] --frame_id Frame --child_frame_id Child_Frame
+
+Static_transform_publisher can also publish a static coordinate transform to tf2 using an x/y/z offset in meters and quaternion.


Suggested change

Static_transform_publisher can also publish a static coordinate transform to tf2 using an x/y/z offset in meters and quaternion.

``static_transform_publisher`` can also publish a static coordinate transform to tf2 using an x/y/z offset in meters and quaternion.

ahcorde · 2024-05-20T13:13:48Z

tf2_ros/doc/cli_tools.rst

+
+  ros2 run tf2_ros static_transform_publisher [--x X] [--y Y] [--z Z] [--qx QX] [--qy QY] [--qz QZ] [--qw QW] --frame_id Frame --child_frame_id Child_Frame
+
+Static_transform_publisher is designed both as a command-line tool for manual use, as well as for use within roslaunch files for setting static transforms. For example:


Suggested change

Static_transform_publisher is designed both as a command-line tool for manual use, as well as for use within roslaunch files for setting static transforms. For example:

``static_transform_publisher`` is designed both as a command-line tool for manual use, as well as for use within roslaunch files for setting static transforms. For example:

ahcorde · 2024-05-20T13:14:03Z

tf2_ros/doc/conf.py

+     'Miscellaneous'),
+]
+
+# Configuration for breathe to link doxygen


ahcorde · 2024-05-20T13:15:01Z

tf2_ros/doc/index.rst

+1.3 Filtering Transforms
+------------------------
+
+tf2_ros provides a feature which allows to pass only the messages once there is transform data available. This follows the pattern from the message_filters package. Here is a brief list of functions that the user is most likely to use.


Suggested change

tf2_ros provides a feature which allows to pass only the messages once there is transform data available. This follows the pattern from the message_filters package. Here is a brief list of functions that the user is most likely to use.

``tf2_ros`` provides a feature which allows to pass only the messages once there is transform data available. This follows the pattern from the ``message_filters`` package. Here is a brief list of functions that the user is most likely to use.

ahcorde · 2024-05-20T13:15:09Z

tf2_ros/doc/index.rst

+1.4 Exceptions
+--------------
+
+Here is the list of exceptions that can be thrown by tf2_ros and are inherited from tf2.


Suggested change

Here is the list of exceptions that can be thrown by tf2_ros and are inherited from tf2.

Here is the list of exceptions that can be thrown by ``tf2_ros`` and are inherited from tf2.

Signed-off-by: CursedRock17 <[email protected]>

ahcorde

I made these changes to be able to get the links

tf2_ros/doc/index.rst

Signed-off-by: CursedRock17 <[email protected]>

ahcorde · 2024-05-21T20:47:20Z

Linux
Linux-aarch64
Windows

ahcorde

Linters are failing https://ci.ros2.org/job/ci_linux/21127/

Signed-off-by: CursedRock17 <[email protected]>

ahcorde · 2024-05-22T07:49:43Z

Linux
Linux-aarch64
Windows

CursedRock17 added 4 commits February 19, 2024 19:40

Moving Docs

c716a29

Signed-off-by: CursedRock17 <[email protected]>

Removing Accidental Build

434208e

Signed-off-by: CursedRock17 <[email protected]>

Correcting the conf.py file

067a0e2

Signed-off-by: CursedRock17 <[email protected]>

Further Removals

878af82

Signed-off-by: CursedRock17 <[email protected]>

CursedRock17 requested review from ahcorde and clalancette as code owners February 20, 2024 00:58

tfoote reviewed Feb 22, 2024

View reviewed changes

Adding rosdoc2

9dfb56a

Signed-off-by: CursedRock17 <[email protected]>

ahcorde requested changes Feb 22, 2024

View reviewed changes

CursedRock17 added 2 commits February 22, 2024 23:21

Allowing Local Links

6354068

Signed-off-by: CursedRock17 <[email protected]>

Adding method tag instead of class

2aa3caf

Signed-off-by: CursedRock17 <[email protected]>

ahcorde requested changes Feb 26, 2024

View reviewed changes

CursedRock17 added 5 commits February 26, 2024 13:30

Removing excess

649b2d0

Signed-off-by: CursedRock17 <[email protected]>

Adding local links to sphinx

1ca38b6

Signed-off-by: CursedRock17 <[email protected]>

Adding rqt_tree image

4d61ea3

Signed-off-by: CursedRock17 <[email protected]>

Adding rqt_tree screenshot

4208e59

Signed-off-by: CursedRock17 <[email protected]>

Adding better language

db710bb

Signed-off-by: CursedRock17 <[email protected]>

clalancette assigned ahcorde Apr 18, 2024

ahcorde mentioned this pull request Apr 19, 2024

Nomenclature of tf_echo and tf_listener ros2/ros2_documentation#4239

Open

Renaming files

8e38be6

Signed-off-by: CursedRock17 <[email protected]> Removing exhale Signed-off-by: CursedRock17 <[email protected]> Fixing doxyfile Signed-off-by: CursedRock17 <[email protected]> Removing extra picture Signed-off-by: CursedRock17 <[email protected]>

CursedRock17 force-pushed the cli_tools_documentation branch from bf86132 to 8e38be6 Compare April 21, 2024 18:08

Adding Hierarchy

93baa88

Signed-off-by: CursedRock17 <[email protected]>

ahcorde requested changes May 20, 2024

View reviewed changes

Linting chagnes

f07d23b

Signed-off-by: CursedRock17 <[email protected]>

ahcorde requested changes May 21, 2024

View reviewed changes

tf2_ros/doc/index.rst Outdated Show resolved Hide resolved

tf2_ros/doc/index.rst Outdated Show resolved Hide resolved

tf2_ros/doc/index.rst Outdated Show resolved Hide resolved

tf2_ros/doc/index.rst Outdated Show resolved Hide resolved

Link Updates

54cef80

Signed-off-by: CursedRock17 <[email protected]>

ahcorde approved these changes May 21, 2024

View reviewed changes

ahcorde requested changes May 21, 2024

View reviewed changes

Fixing uncrustify

35994aa

Signed-off-by: CursedRock17 <[email protected]>

ahcorde approved these changes May 22, 2024

View reviewed changes

ahcorde merged commit c9ca2ca into ros2:rolling May 22, 2024
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cli tools documentation #653

Cli tools documentation #653

CursedRock17 commented Feb 20, 2024

tfoote left a comment

tfoote Feb 21, 2024

CursedRock17 Feb 29, 2024

CursedRock17 commented Feb 22, 2024

ros-discourse commented Apr 7, 2024

ahcorde commented Apr 19, 2024

CursedRock17 commented Apr 21, 2024

ahcorde left a comment

ahcorde Apr 19, 2024

ahcorde May 20, 2024

ahcorde May 20, 2024

ahcorde May 20, 2024

ahcorde May 20, 2024

ahcorde May 20, 2024

ahcorde May 20, 2024

ahcorde May 20, 2024

ahcorde May 20, 2024

ahcorde May 20, 2024

ahcorde left a comment

ahcorde commented May 21, 2024

ahcorde left a comment

ahcorde commented May 22, 2024

	Raised when the arguments to the method are called improperly formed. An example of why this might be raised is if an argument is nan.
	Raised when the arguments to the method are called improperly formed. An example of why this might be raised is if an argument is nan.


		ros2 run turtlesim turtle_teleop_key

		Now using tf2_echo to take a look at the different transformations occuring between two frames

	tf2_echo is the simplest tool to look at the numeric values of a specific transform. tf2_echo takes two arguments: the source frame and the target frame. The output of tf2_echo is the target frame in comparison to the source frame. E.g. to get the transformation from turtle1 to turtle2, set up the turtlesim example with:
	``tf2_echo`` is the simplest tool to look at the numeric values of a specific transform. ``tf2_echo`` takes two arguments: the source frame and the target frame. The output of ``tf2_echo`` is the target frame in comparison to the source frame. E.g. to get the transformation from turtle1 to turtle2, set up the turtlesim example with:

	A simple tree from the tutorial in 1. tf2_echo looks like:
	A simple tree from the tutorial in 1. ``tf2_echo`` looks like:

	tf2_monitor can give you a lot of detailed information about a specific transformation you care about. The monitor will break down the chain between two frames into individual transforms, and provide statistics about timing, broadcasters, etc.
	``tf2_monitor`` can give you a lot of detailed information about a specific transformation you care about. The monitor will break down the chain between two frames into individual transforms, and provide statistics about timing, broadcasters, etc.


		ros2 run tf2_ros static_transform_publisher [--x X] [--y Y] [--z Z] [--yaw Yaw] [--pitch Pitch] [--roll Roll] --frame_id Frame --child_frame_id Child_Frame

		Static_transform_publisher can also publish a static coordinate transform to tf2 using an x/y/z offset in meters and quaternion.

	Static_transform_publisher can also publish a static coordinate transform to tf2 using an x/y/z offset in meters and quaternion.
	``static_transform_publisher`` can also publish a static coordinate transform to tf2 using an x/y/z offset in meters and quaternion.


		ros2 run tf2_ros static_transform_publisher [--x X] [--y Y] [--z Z] [--qx QX] [--qy QY] [--qz QZ] [--qw QW] --frame_id Frame --child_frame_id Child_Frame

		Static_transform_publisher is designed both as a command-line tool for manual use, as well as for use within roslaunch files for setting static transforms. For example:

	Static_transform_publisher is designed both as a command-line tool for manual use, as well as for use within roslaunch files for setting static transforms. For example:
	``static_transform_publisher`` is designed both as a command-line tool for manual use, as well as for use within roslaunch files for setting static transforms. For example:

	tf2_ros provides a feature which allows to pass only the messages once there is transform data available. This follows the pattern from the message_filters package. Here is a brief list of functions that the user is most likely to use.
	``tf2_ros`` provides a feature which allows to pass only the messages once there is transform data available. This follows the pattern from the ``message_filters`` package. Here is a brief list of functions that the user is most likely to use.

	Here is the list of exceptions that can be thrown by tf2_ros and are inherited from tf2.
	Here is the list of exceptions that can be thrown by ``tf2_ros`` and are inherited from tf2.

Cli tools documentation #653

Cli tools documentation #653

Conversation

CursedRock17 commented Feb 20, 2024

tfoote left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CursedRock17 commented Feb 22, 2024

ros-discourse commented Apr 7, 2024

ahcorde commented Apr 19, 2024

CursedRock17 commented Apr 21, 2024

ahcorde left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ahcorde left a comment

Choose a reason for hiding this comment

ahcorde commented May 21, 2024

ahcorde left a comment

Choose a reason for hiding this comment

ahcorde commented May 22, 2024