Advertise AnyReader in documentation

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 pathlib import Path
-   from rosbags.serde import deserialize_cdr
+
+   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)
 
 

docs/index.rst

@@ -10,6 +10,7 @@
    :maxdepth: 1
    :hidden:
 
+   topics/highlevel
    topics/typesys
    topics/serde
    topics/rosbag2

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.