reorganize docs

Author: jlblancoc

docs/source/ros2api.rst

@@ -11,15 +11,8 @@ or LiDAR-odometry module. At present, this applies to:
   MOLA modules and the ROS 2 system.
 - :ref:`mola_lidar_odometry`
 
-.. note::
-
-   It is recommended to start with the tutorial on how to :ref:`build a map <building-maps>`,
-   then check out :ref:`how to launch MOLA-LO for ROS 2 <mola_lo_ros>`.
-
 .. image:: https://mrpt.github.io/imgs/mola-lo-ros2-launch-demo-kitti.png
 
-
-
 ____________________________________________
 
 .. contents:: Table of Contents
@@ -31,7 +24,32 @@ ____________________________________________
 
 |
 
-1. Map loading / saving
+1. Launching MOLA-LO ROS 2 node
+--------------------------------------
+
+Basic usage:
+
+   .. code-block:: bash
+
+      # Basic usage (requires correct LiDAR sensor /tf):
+      ros2 launch mola_lidar_odometry ros2-lidar-odometry.launch.py \
+      lidar_topic_name:=/ouster/points
+
+      # Usage without sensor /tf:
+      ros2 launch mola_lidar_odometry ros2-lidar-odometry.launch.py \
+      lidar_topic_name:=/ouster/points \
+      ignore_lidar_pose_from_tf:=True
+
+.. note::
+
+   It is recommended to start with the tutorial on how to :ref:`build a map <building-maps>`,
+   then read :ref:`the docs <mola_lo_ros>` on the MOLA-LO ROS 2 launch file.
+
+|
+
+----
+
+2. Map loading / saving
 --------------------------------------
 During a live SLAM run, ``BridgeROS2`` will look for modules implementing
 :ref:`MapServer <doxid-classmola_1_1_map_server>` and will expose
@@ -43,13 +61,13 @@ these **ROS 2 services** to load or save the current map:
 
 .. dropdown:: Example ROS 2 cli service calls
 
-    To save the current map:
+   To save the current map:
 
    .. code-block:: bash
 
       ros2 service call /map_save mola_msgs/srv/MapSave "map_path: '/tmp/my_map_file_prefix'"
 
-    To load a map from disk:
+   To load a map from disk:
 
    .. code-block:: bash
 
@@ -70,7 +88,7 @@ the corresponding checkbox in the
 
 ----
 
-2. Re-localization
+3. Re-localization
 --------------------------------------
 Write me!
 
@@ -80,7 +98,7 @@ Write me!
 
 .. _mola_ros2_tf_frames:
 
-3. ``/tf`` frames
+4. Published ``/tf`` frames
 --------------------------------------
 These frames of reference exist when using MOLA :ref:`geo-referenced <geo-referencing>` maps:
 
@@ -116,7 +134,7 @@ And this is who is responsible of publishing each transformation:
 
 ----
 
-4. Map publishing
+5. Map publishing
 --------------------------------------
 There are two ways of publishing maps to ROS:
 

docs/source/tutorial-mola-lo-map-and-localize.rst

@@ -0,0 +1,64 @@
+.. _tutorial-mola-lo-map-and-localize:
+
+===============================================
+MOLA-LO: Build a map and then localize
+===============================================
+
+This tutorial will show you how to build a map using MOLA-LO, then save the map to disk, 
+and how to load that map to use the LO localization mode.
+
+.. contents::
+   :depth: 1
+   :local:
+   :backlinks: none
+
+|
+
+MOLA installation
+----------------------------------
+This tutorial requires the installation of these MOLA packages: ``mola_demos``, ``mola_viz``.
+
+Following the default :ref:`installation instructions <installing>` is enough.
+
+It also uses the MVSim simulator, although a live robot or LiDAR sensor can be used instead.
+
+|
+
+Create a map and save it
+----------------------------------
+
+Open three (3) terminals, and run these commands in each one:
+
+In terminal #1, launch the simulator (or your custom launch for your real sensor):
+
+.. code-block:: bash
+
+    ros2 launch mvsim demo_warehouse.launch.py \
+      do_fake_localization:=False \
+      with_rviz:=False
+
+|
+
+In terminal #2, launch MOLA-LO, enabling saving the map in simple-map format:
+
+.. code-block:: bash
+
+    MOLA_GENERATE_SIMPLEMAP=true \
+    ros2 launch mola_lidar_odometry ros2-lidar-odometry.launch.py \
+      lidar_topic_name:=/lidar1_points
+
+.. note::
+
+  Remember replacing ``/lidar1_points`` with your actual PointCloud2 topic with raw LiDAR data.
+
+Next, move the robot around. In the simulator, you can click on the MVSim GUI and use keys ``asdw`` to drive around, or use a gamepad.
+
+|
+
+Once the map looks OK in the mola_viz GUI, let's save it.
+In terminal #3, run:
+
+.. code-block:: bash
+
+    ros2 service call /map_save mola_msgs/srv/MapSave "map_path: '/tmp/my_map'"
+

docs/source/tutorials.rst

@@ -4,20 +4,18 @@
 Tutorials
 =============
 
-.. note::
-
-  This page refers to core MOLA packages. For higher-level SLAM tutorials,
-  refer to: :ref:`building-maps`.
 
+.. toctree::
+  :maxdepth: 2
+  :caption: SLAM, mapping, localization
 
-These pages gives use-case examples of how to make the existing MOLA modules
-work, how to extend them to create new ones, and how to use the auxiliary MOLA
-tools.
+  building-maps
+  tutorial-mola-lo-map-and-localize
 
-(Write me!)
 
 .. toctree::
   :maxdepth: 2
+  :caption: Core MOLA functionalities
 
   tutorial-mola-main-cli-tools
   tutorial-mola-cmake-commands