From 967328627c728326c087b312ec525008cd964f59 Mon Sep 17 00:00:00 2001
From: Marko Durkovic <marko@ternaris.com>
Date: Thu, 2 Mar 2023 09:37:52 +0100
Subject: [PATCH] Advertise AnyReader in documentation

---
 README.rst                | 12 +++++++-----
 docs/index.rst            |  1 +
 docs/topics/highlevel.rst | 22 ++++++++++++++++++++++
 3 files changed, 30 insertions(+), 5 deletions(-)
 create mode 100644 docs/topics/highlevel.rst

diff --git a/README.rst b/README.rst
index ab378151..b3c19de8 100644
--- a/README.rst
+++ b/README.rst
@@ -15,6 +15,7 @@ Rosbags
 
 Rosbags is the **pure python** library for everything rosbag. It contains:
 
+- **highlevel** easy-to-use interfaces,
 - **rosbag2** reader and writer,
 - **rosbag1** reader and writer,
 - **extensible** type system with serializers and deserializers,
@@ -34,18 +35,19 @@ Rosbags is published on PyPI and does not have any special dependencies. Simply
    pip install rosbags
 
 
-Read and deserialize rosbag2 messages:
+Read and deserialize messages from rosbag1 or rosbag2 files:
 
 .. code-block:: python
 
-   from rosbags.rosbag2 import Reader
-   from rosbags.serde import deserialize_cdr
+   from pathlib import Path
+
+   from rosbags.highlevel import AnyReader
 
    # create reader instance and open for reading
-   with Reader('/home/ros/rosbag_2020_03_24') as reader:
+   with AnyReader([Path('/home/ros/rosbag_2020_03_24')]) as reader:
        connections = [x for x in reader.connections if x.topic == '/imu_raw/Imu']
        for connection, timestamp, rawdata in reader.messages(connections=connections):
-            msg = deserialize_cdr(rawdata, connection.msgtype)
+            msg = reader.deserialize(rawdata, connection.msgtype)
             print(msg.header.frame_id)
 
 
diff --git a/docs/index.rst b/docs/index.rst
index d609e6df..81f4668f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,6 +10,7 @@
    :maxdepth: 1
    :hidden:
 
+   topics/highlevel
    topics/typesys
    topics/serde
    topics/rosbag2
diff --git a/docs/topics/highlevel.rst b/docs/topics/highlevel.rst
new file mode 100644
index 00000000..2aafd106
--- /dev/null
+++ b/docs/topics/highlevel.rst
@@ -0,0 +1,22 @@
+Highlevel APIs
+==============
+The :py:mod:`rosbags.highlevel` package provides classes that abstract the complexity of ROS types, serialization and message access into single easy-to-use interfaces.
+
+All in one reader
+-----------------
+Instances of the :py:class:`AnyReader <rosbags.highlevel.AnyReader>` class give unified access to ROS1 and ROS2 bag files. If a bag file includes message definitions the reader auto-registers all messages into a blank type store, otherwise it falls back to the default type store. It also exposes appropriate deserialization methods on the reader instance itself. 
+
+.. code-block:: python
+
+   from pathlib import Path
+
+   from rosbags.highlevel import AnyReader
+
+   # create reader instance and open for reading
+   with AnyReader([Path('/home/ros/rosbag_2020_03_24')]) as reader:
+       connections = [x for x in reader.connections if x.topic == '/imu_raw/Imu']
+       for connection, timestamp, rawdata in reader.messages(connections=connections):
+            msg = reader.deserialize(rawdata, connection.msgtype)
+            print(msg.header.frame_id)
+
+AnyReader takes a list of ``pathlib.Path`` instances as arguments. It can take either one ROS2 bag file or one or more ROS1 bag files belonging to a split bag. The reader will replay ROS1 split bags in correct timestamp order.