From b924fd4642dbad6ef17daca33c36ccd7196e7556 Mon Sep 17 00:00:00 2001
From: Marko Durkovic <marko@ternaris.com>
Date: Mon, 11 Apr 2022 14:10:38 +0200
Subject: [PATCH] Add documentation for included types

---
 docs/api/rosbags.rst               |   1 +
 docs/api/rosbags.typesys.types.rst |   6 +
 docs/conf.py                       |   1 +
 docs/topics/typesys-types.rst      | 194 +++++++++++++++++++++++++++++
 docs/topics/typesys.rst            |   5 +
 src/rosbags/typesys/__main__.py    |  16 +++
 6 files changed, 223 insertions(+)
 create mode 100644 docs/api/rosbags.typesys.types.rst
 create mode 100644 docs/topics/typesys-types.rst

diff --git a/docs/api/rosbags.rst b/docs/api/rosbags.rst
index 19c8a4f3..e8761f70 100644
--- a/docs/api/rosbags.rst
+++ b/docs/api/rosbags.rst
@@ -9,3 +9,4 @@ Rosbags namespace
    rosbags.rosbag2
    rosbags.serde
    rosbags.typesys
+   rosbags.typesys.types
diff --git a/docs/api/rosbags.typesys.types.rst b/docs/api/rosbags.typesys.types.rst
new file mode 100644
index 00000000..46b5d243
--- /dev/null
+++ b/docs/api/rosbags.typesys.types.rst
@@ -0,0 +1,6 @@
+rosbags.typesys.types
+=====================
+
+.. automodule:: rosbags.typesys.types
+   :members:
+   :show-inheritance:
diff --git a/docs/conf.py b/docs/conf.py
index 17b2ed43..ace01c87 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -22,6 +22,7 @@ copyright = '2020-2022, Ternaris'
 author = 'Ternaris'
 
 autoapi_python_use_implicit_namespaces = True
+autodoc_typehints = 'description'
 
 extensions = [
     'sphinx.ext.autodoc',
diff --git a/docs/topics/typesys-types.rst b/docs/topics/typesys-types.rst
new file mode 100644
index 00000000..6c8cfb60
--- /dev/null
+++ b/docs/topics/typesys-types.rst
@@ -0,0 +1,194 @@
+builtin_interfaces
+******************
+- :py:class:`Duration <rosbags.typesys.types.builtin_interfaces__msg__Duration>`
+- :py:class:`Time <rosbags.typesys.types.builtin_interfaces__msg__Time>`
+
+diagnostic_msgs
+***************
+- :py:class:`DiagnosticArray <rosbags.typesys.types.diagnostic_msgs__msg__DiagnosticArray>`
+- :py:class:`DiagnosticStatus <rosbags.typesys.types.diagnostic_msgs__msg__DiagnosticStatus>`
+- :py:class:`KeyValue <rosbags.typesys.types.diagnostic_msgs__msg__KeyValue>`
+
+geometry_msgs
+*************
+- :py:class:`Accel <rosbags.typesys.types.geometry_msgs__msg__Accel>`
+- :py:class:`AccelStamped <rosbags.typesys.types.geometry_msgs__msg__AccelStamped>`
+- :py:class:`AccelWithCovariance <rosbags.typesys.types.geometry_msgs__msg__AccelWithCovariance>`
+- :py:class:`AccelWithCovarianceStamped <rosbags.typesys.types.geometry_msgs__msg__AccelWithCovarianceStamped>`
+- :py:class:`Inertia <rosbags.typesys.types.geometry_msgs__msg__Inertia>`
+- :py:class:`InertiaStamped <rosbags.typesys.types.geometry_msgs__msg__InertiaStamped>`
+- :py:class:`Point <rosbags.typesys.types.geometry_msgs__msg__Point>`
+- :py:class:`Point32 <rosbags.typesys.types.geometry_msgs__msg__Point32>`
+- :py:class:`PointStamped <rosbags.typesys.types.geometry_msgs__msg__PointStamped>`
+- :py:class:`Polygon <rosbags.typesys.types.geometry_msgs__msg__Polygon>`
+- :py:class:`PolygonStamped <rosbags.typesys.types.geometry_msgs__msg__PolygonStamped>`
+- :py:class:`Pose <rosbags.typesys.types.geometry_msgs__msg__Pose>`
+- :py:class:`Pose2D <rosbags.typesys.types.geometry_msgs__msg__Pose2D>`
+- :py:class:`PoseArray <rosbags.typesys.types.geometry_msgs__msg__PoseArray>`
+- :py:class:`PoseStamped <rosbags.typesys.types.geometry_msgs__msg__PoseStamped>`
+- :py:class:`PoseWithCovariance <rosbags.typesys.types.geometry_msgs__msg__PoseWithCovariance>`
+- :py:class:`PoseWithCovarianceStamped <rosbags.typesys.types.geometry_msgs__msg__PoseWithCovarianceStamped>`
+- :py:class:`Quaternion <rosbags.typesys.types.geometry_msgs__msg__Quaternion>`
+- :py:class:`QuaternionStamped <rosbags.typesys.types.geometry_msgs__msg__QuaternionStamped>`
+- :py:class:`Transform <rosbags.typesys.types.geometry_msgs__msg__Transform>`
+- :py:class:`TransformStamped <rosbags.typesys.types.geometry_msgs__msg__TransformStamped>`
+- :py:class:`Twist <rosbags.typesys.types.geometry_msgs__msg__Twist>`
+- :py:class:`TwistStamped <rosbags.typesys.types.geometry_msgs__msg__TwistStamped>`
+- :py:class:`TwistWithCovariance <rosbags.typesys.types.geometry_msgs__msg__TwistWithCovariance>`
+- :py:class:`TwistWithCovarianceStamped <rosbags.typesys.types.geometry_msgs__msg__TwistWithCovarianceStamped>`
+- :py:class:`Vector3 <rosbags.typesys.types.geometry_msgs__msg__Vector3>`
+- :py:class:`Vector3Stamped <rosbags.typesys.types.geometry_msgs__msg__Vector3Stamped>`
+- :py:class:`Wrench <rosbags.typesys.types.geometry_msgs__msg__Wrench>`
+- :py:class:`WrenchStamped <rosbags.typesys.types.geometry_msgs__msg__WrenchStamped>`
+
+libstatistics_collector
+***********************
+- :py:class:`DummyMessage <rosbags.typesys.types.libstatistics_collector__msg__DummyMessage>`
+
+lifecycle_msgs
+**************
+- :py:class:`State <rosbags.typesys.types.lifecycle_msgs__msg__State>`
+- :py:class:`Transition <rosbags.typesys.types.lifecycle_msgs__msg__Transition>`
+- :py:class:`TransitionDescription <rosbags.typesys.types.lifecycle_msgs__msg__TransitionDescription>`
+- :py:class:`TransitionEvent <rosbags.typesys.types.lifecycle_msgs__msg__TransitionEvent>`
+
+nav_msgs
+********
+- :py:class:`GridCells <rosbags.typesys.types.nav_msgs__msg__GridCells>`
+- :py:class:`MapMetaData <rosbags.typesys.types.nav_msgs__msg__MapMetaData>`
+- :py:class:`OccupancyGrid <rosbags.typesys.types.nav_msgs__msg__OccupancyGrid>`
+- :py:class:`Odometry <rosbags.typesys.types.nav_msgs__msg__Odometry>`
+- :py:class:`Path <rosbags.typesys.types.nav_msgs__msg__Path>`
+
+rcl_interfaces
+**************
+- :py:class:`FloatingPointRange <rosbags.typesys.types.rcl_interfaces__msg__FloatingPointRange>`
+- :py:class:`IntegerRange <rosbags.typesys.types.rcl_interfaces__msg__IntegerRange>`
+- :py:class:`ListParametersResult <rosbags.typesys.types.rcl_interfaces__msg__ListParametersResult>`
+- :py:class:`Log <rosbags.typesys.types.rcl_interfaces__msg__Log>`
+- :py:class:`Parameter <rosbags.typesys.types.rcl_interfaces__msg__Parameter>`
+- :py:class:`ParameterDescriptor <rosbags.typesys.types.rcl_interfaces__msg__ParameterDescriptor>`
+- :py:class:`ParameterEvent <rosbags.typesys.types.rcl_interfaces__msg__ParameterEvent>`
+- :py:class:`ParameterEventDescriptors <rosbags.typesys.types.rcl_interfaces__msg__ParameterEventDescriptors>`
+- :py:class:`ParameterType <rosbags.typesys.types.rcl_interfaces__msg__ParameterType>`
+- :py:class:`ParameterValue <rosbags.typesys.types.rcl_interfaces__msg__ParameterValue>`
+- :py:class:`SetParametersResult <rosbags.typesys.types.rcl_interfaces__msg__SetParametersResult>`
+
+rmw_dds_common
+**************
+- :py:class:`Gid <rosbags.typesys.types.rmw_dds_common__msg__Gid>`
+- :py:class:`NodeEntitiesInfo <rosbags.typesys.types.rmw_dds_common__msg__NodeEntitiesInfo>`
+- :py:class:`ParticipantEntitiesInfo <rosbags.typesys.types.rmw_dds_common__msg__ParticipantEntitiesInfo>`
+
+rosgraph_msgs
+*************
+- :py:class:`Clock <rosbags.typesys.types.rosgraph_msgs__msg__Clock>`
+
+sensor_msgs
+***********
+- :py:class:`BatteryState <rosbags.typesys.types.sensor_msgs__msg__BatteryState>`
+- :py:class:`CameraInfo <rosbags.typesys.types.sensor_msgs__msg__CameraInfo>`
+- :py:class:`ChannelFloat32 <rosbags.typesys.types.sensor_msgs__msg__ChannelFloat32>`
+- :py:class:`CompressedImage <rosbags.typesys.types.sensor_msgs__msg__CompressedImage>`
+- :py:class:`FluidPressure <rosbags.typesys.types.sensor_msgs__msg__FluidPressure>`
+- :py:class:`Illuminance <rosbags.typesys.types.sensor_msgs__msg__Illuminance>`
+- :py:class:`Image <rosbags.typesys.types.sensor_msgs__msg__Image>`
+- :py:class:`Imu <rosbags.typesys.types.sensor_msgs__msg__Imu>`
+- :py:class:`JointState <rosbags.typesys.types.sensor_msgs__msg__JointState>`
+- :py:class:`Joy <rosbags.typesys.types.sensor_msgs__msg__Joy>`
+- :py:class:`JoyFeedback <rosbags.typesys.types.sensor_msgs__msg__JoyFeedback>`
+- :py:class:`JoyFeedbackArray <rosbags.typesys.types.sensor_msgs__msg__JoyFeedbackArray>`
+- :py:class:`LaserEcho <rosbags.typesys.types.sensor_msgs__msg__LaserEcho>`
+- :py:class:`LaserScan <rosbags.typesys.types.sensor_msgs__msg__LaserScan>`
+- :py:class:`MagneticField <rosbags.typesys.types.sensor_msgs__msg__MagneticField>`
+- :py:class:`MultiDOFJointState <rosbags.typesys.types.sensor_msgs__msg__MultiDOFJointState>`
+- :py:class:`MultiEchoLaserScan <rosbags.typesys.types.sensor_msgs__msg__MultiEchoLaserScan>`
+- :py:class:`NavSatFix <rosbags.typesys.types.sensor_msgs__msg__NavSatFix>`
+- :py:class:`NavSatStatus <rosbags.typesys.types.sensor_msgs__msg__NavSatStatus>`
+- :py:class:`PointCloud <rosbags.typesys.types.sensor_msgs__msg__PointCloud>`
+- :py:class:`PointCloud2 <rosbags.typesys.types.sensor_msgs__msg__PointCloud2>`
+- :py:class:`PointField <rosbags.typesys.types.sensor_msgs__msg__PointField>`
+- :py:class:`Range <rosbags.typesys.types.sensor_msgs__msg__Range>`
+- :py:class:`RegionOfInterest <rosbags.typesys.types.sensor_msgs__msg__RegionOfInterest>`
+- :py:class:`RelativeHumidity <rosbags.typesys.types.sensor_msgs__msg__RelativeHumidity>`
+- :py:class:`Temperature <rosbags.typesys.types.sensor_msgs__msg__Temperature>`
+- :py:class:`TimeReference <rosbags.typesys.types.sensor_msgs__msg__TimeReference>`
+
+shape_msgs
+**********
+- :py:class:`Mesh <rosbags.typesys.types.shape_msgs__msg__Mesh>`
+- :py:class:`MeshTriangle <rosbags.typesys.types.shape_msgs__msg__MeshTriangle>`
+- :py:class:`Plane <rosbags.typesys.types.shape_msgs__msg__Plane>`
+- :py:class:`SolidPrimitive <rosbags.typesys.types.shape_msgs__msg__SolidPrimitive>`
+
+statistics_msgs
+***************
+- :py:class:`MetricsMessage <rosbags.typesys.types.statistics_msgs__msg__MetricsMessage>`
+- :py:class:`StatisticDataPoint <rosbags.typesys.types.statistics_msgs__msg__StatisticDataPoint>`
+- :py:class:`StatisticDataType <rosbags.typesys.types.statistics_msgs__msg__StatisticDataType>`
+
+std_msgs
+********
+- :py:class:`Bool <rosbags.typesys.types.std_msgs__msg__Bool>`
+- :py:class:`Byte <rosbags.typesys.types.std_msgs__msg__Byte>`
+- :py:class:`ByteMultiArray <rosbags.typesys.types.std_msgs__msg__ByteMultiArray>`
+- :py:class:`Char <rosbags.typesys.types.std_msgs__msg__Char>`
+- :py:class:`ColorRGBA <rosbags.typesys.types.std_msgs__msg__ColorRGBA>`
+- :py:class:`Empty <rosbags.typesys.types.std_msgs__msg__Empty>`
+- :py:class:`Float32 <rosbags.typesys.types.std_msgs__msg__Float32>`
+- :py:class:`Float32MultiArray <rosbags.typesys.types.std_msgs__msg__Float32MultiArray>`
+- :py:class:`Float64 <rosbags.typesys.types.std_msgs__msg__Float64>`
+- :py:class:`Float64MultiArray <rosbags.typesys.types.std_msgs__msg__Float64MultiArray>`
+- :py:class:`Header <rosbags.typesys.types.std_msgs__msg__Header>`
+- :py:class:`Int16 <rosbags.typesys.types.std_msgs__msg__Int16>`
+- :py:class:`Int16MultiArray <rosbags.typesys.types.std_msgs__msg__Int16MultiArray>`
+- :py:class:`Int32 <rosbags.typesys.types.std_msgs__msg__Int32>`
+- :py:class:`Int32MultiArray <rosbags.typesys.types.std_msgs__msg__Int32MultiArray>`
+- :py:class:`Int64 <rosbags.typesys.types.std_msgs__msg__Int64>`
+- :py:class:`Int64MultiArray <rosbags.typesys.types.std_msgs__msg__Int64MultiArray>`
+- :py:class:`Int8 <rosbags.typesys.types.std_msgs__msg__Int8>`
+- :py:class:`Int8MultiArray <rosbags.typesys.types.std_msgs__msg__Int8MultiArray>`
+- :py:class:`MultiArrayDimension <rosbags.typesys.types.std_msgs__msg__MultiArrayDimension>`
+- :py:class:`MultiArrayLayout <rosbags.typesys.types.std_msgs__msg__MultiArrayLayout>`
+- :py:class:`String <rosbags.typesys.types.std_msgs__msg__String>`
+- :py:class:`UInt16 <rosbags.typesys.types.std_msgs__msg__UInt16>`
+- :py:class:`UInt16MultiArray <rosbags.typesys.types.std_msgs__msg__UInt16MultiArray>`
+- :py:class:`UInt32 <rosbags.typesys.types.std_msgs__msg__UInt32>`
+- :py:class:`UInt32MultiArray <rosbags.typesys.types.std_msgs__msg__UInt32MultiArray>`
+- :py:class:`UInt64 <rosbags.typesys.types.std_msgs__msg__UInt64>`
+- :py:class:`UInt64MultiArray <rosbags.typesys.types.std_msgs__msg__UInt64MultiArray>`
+- :py:class:`UInt8 <rosbags.typesys.types.std_msgs__msg__UInt8>`
+- :py:class:`UInt8MultiArray <rosbags.typesys.types.std_msgs__msg__UInt8MultiArray>`
+
+stereo_msgs
+***********
+- :py:class:`DisparityImage <rosbags.typesys.types.stereo_msgs__msg__DisparityImage>`
+
+tf2_msgs
+********
+- :py:class:`TF2Error <rosbags.typesys.types.tf2_msgs__msg__TF2Error>`
+- :py:class:`TFMessage <rosbags.typesys.types.tf2_msgs__msg__TFMessage>`
+
+trajectory_msgs
+***************
+- :py:class:`JointTrajectory <rosbags.typesys.types.trajectory_msgs__msg__JointTrajectory>`
+- :py:class:`JointTrajectoryPoint <rosbags.typesys.types.trajectory_msgs__msg__JointTrajectoryPoint>`
+- :py:class:`MultiDOFJointTrajectory <rosbags.typesys.types.trajectory_msgs__msg__MultiDOFJointTrajectory>`
+- :py:class:`MultiDOFJointTrajectoryPoint <rosbags.typesys.types.trajectory_msgs__msg__MultiDOFJointTrajectoryPoint>`
+
+unique_identifier_msgs
+**********************
+- :py:class:`UUID <rosbags.typesys.types.unique_identifier_msgs__msg__UUID>`
+
+visualization_msgs
+******************
+- :py:class:`ImageMarker <rosbags.typesys.types.visualization_msgs__msg__ImageMarker>`
+- :py:class:`InteractiveMarker <rosbags.typesys.types.visualization_msgs__msg__InteractiveMarker>`
+- :py:class:`InteractiveMarkerControl <rosbags.typesys.types.visualization_msgs__msg__InteractiveMarkerControl>`
+- :py:class:`InteractiveMarkerFeedback <rosbags.typesys.types.visualization_msgs__msg__InteractiveMarkerFeedback>`
+- :py:class:`InteractiveMarkerInit <rosbags.typesys.types.visualization_msgs__msg__InteractiveMarkerInit>`
+- :py:class:`InteractiveMarkerPose <rosbags.typesys.types.visualization_msgs__msg__InteractiveMarkerPose>`
+- :py:class:`InteractiveMarkerUpdate <rosbags.typesys.types.visualization_msgs__msg__InteractiveMarkerUpdate>`
+- :py:class:`Marker <rosbags.typesys.types.visualization_msgs__msg__Marker>`
+- :py:class:`MarkerArray <rosbags.typesys.types.visualization_msgs__msg__MarkerArray>`
+- :py:class:`MenuEntry <rosbags.typesys.types.visualization_msgs__msg__MenuEntry>`
diff --git a/docs/topics/typesys.rst b/docs/topics/typesys.rst
index 26c19274..b846adc4 100644
--- a/docs/topics/typesys.rst
+++ b/docs/topics/typesys.rst
@@ -13,6 +13,11 @@ The type system generates a dataclass for each message type. These dataclasses g
 
    Limitation: While the type system parses message definitions with array bounds and/or default values, neither bounds nor default values are enforced or assigned to message instances.
 
+Included message types
+----------------------
+
+.. include:: ./typesys-types.rst
+
 Extending the type system
 -------------------------
 Adding custom message types consists of two steps. First, message definitions are converted into parse trees using :py:func:`get_types_from_idl() <rosbags.typesys.get_types_from_idl>` or :py:func:`get_types_from_msg() <rosbags.typesys.get_types_from_msg>`, and second the types are registered in the type system via :py:func:`register_types() <rosbags.typesys.register_types>`. The following example shows how to add messages type definitions from ``.msg`` and ``.idl`` files:
diff --git a/src/rosbags/typesys/__main__.py b/src/rosbags/typesys/__main__.py
index 5f9f957f..f7dd37ff 100644
--- a/src/rosbags/typesys/__main__.py
+++ b/src/rosbags/typesys/__main__.py
@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+from itertools import groupby
 from os import walk
 from pathlib import Path
 from typing import TYPE_CHECKING
@@ -16,6 +17,19 @@ if TYPE_CHECKING:
     from .base import Typesdict
 
 
+def generate_docs(typs: Typesdict) -> str:
+    """Generate types documentation."""
+    res = []
+    for namespace, msgs in groupby([x.split('/msg/') for x in typs], key=lambda x: x[0]):
+        res.append(namespace)
+        res.append('*' * len(namespace))
+
+        for _, msg in msgs:
+            res.append(f'- :py:class:`{msg} <rosbags.typesys.types.{namespace}__msg__{msg}>`')
+        res.append('')
+    return '\n'.join(res)
+
+
 def main() -> None:  # pragma: no cover
     """Update builtin types.
 
@@ -24,6 +38,7 @@ def main() -> None:  # pragma: no cover
     """
     typs: Typesdict = {}
     selfdir = Path(__file__).parent
+    projectdir = selfdir.parent.parent.parent
     for root, dirnames, files in walk(selfdir.parents[2] / 'tools' / 'messages'):
         if '.rosbags_ignore' in files:
             dirnames.clear()
@@ -40,6 +55,7 @@ def main() -> None:  # pragma: no cover
     typs = dict(sorted(typs.items()))
     register_types(typs)
     (selfdir / 'types.py').write_text(generate_python_code(typs))
+    (projectdir / 'docs' / 'topics' / 'typesys-types.rst').write_text(generate_docs(typs))
 
 
 if __name__ == '__main__':