docs: Link to trifinger_docs & more concise sim/real-interface description

docs/conf.py

@@ -73,7 +73,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -97,6 +97,10 @@
 
 # == intersphinx ==
 intersphinx_mapping = {
+    "trifinger_docs": (
+        "https://open-dynamic-robot-initiative.github.io/trifinger_docs",
+        None,
+    ),
     "robot_fingers": (
         "https://open-dynamic-robot-initiative.github.io/robot_fingers",
         None,

docs/getting_started/installation.rst

@@ -75,6 +75,6 @@ or by running one of the demos::
 Using colcon
 ------------
 
-trifinger_simulation is part of the "ROBOT_FINGERS" project.  For build
-instructions see the :doc:`robot_fingers documentation
-<robot_fingers:doc/installation>`.
+The ``trifinger_simulation`` package is also part of the TriFinger software
+bundle.  See :ref:`trifinger_docs:install_software` in the TriFinger
+documentation.

docs/index.rst

@@ -5,12 +5,13 @@ Welcome to the TriFinger Robot Simulation docs!
 .. image:: images/all_finger_types.jpg
    :alt: Screenshots of different (Tri)Finger robots in simulation
 
-The trifinger_simulation_ package contains a PyBullet simulation environment
-for the different TriFinger robots as well as helper functions for some tasks
-(for sampling goals, computing rewards, etc.).
+The trifinger_simulation_ package contains a PyBullet_ simulation environment
+for the different :doc:`TriFinger robots <trifinger_docs:index>` as well as helper
+functions for some tasks (for sampling goals, computing rewards, etc.).
 
-To learn more about the TriFinger robots, check out the `TriFinger project
-website`_ and the corresponding paper_.
+To learn more about the TriFinger robots, check out our paper_ (and the corresponding
+`webpage <https://sites.google.com/view/trifinger>`_) and the overarching
+:doc:`TriFinger documentation <trifinger_docs:index>`.
 
 
 .. toctree::
@@ -23,10 +24,9 @@ website`_ and the corresponding paper_.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Ease of Use with a Real Robot
+   :caption: Guides
 
    simreal/simwithreal
-   simreal/realwithsim
    simreal/simvsreal
    simreal/timesteplogic
 
@@ -81,8 +81,8 @@ please cite this repository and also the corresponding paper:
     }
 
 .. _trifinger_simulation: https://github.com/open-dynamic-robot-initiative/trifinger_simulation
-.. _`TriFinger project website`: https://sites.google.com/view/trifinger
 .. _paper: https://arxiv.org/abs/2008.03596
+.. _PyBullet: https://pybullet.org
 
 
 ----

docs/simreal/simvsreal.rst

@@ -1,20 +1,22 @@
 .. _sec-simulation-vs-real-robot:
 
-*********************************************
-Differences between Simulation and Real Robot
-*********************************************
+************************
+Simulation vs Real Robot
+************************
 
-The ``SimFinger`` class provides us with an API to control the TriFinger robots in
-simulation. Similarly, the `robot_interfaces::RobotFrontend`_ class provides an
-API to interact with these robots in real life.
+The :class:`~trifinger_simulation.sim_finger.SimFinger` class provides an API to control
+the TriFinger robots in simulation. Similarly, the
+:cpp:class:`robot_interfaces::RobotFrontend` class provides an API to interact with
+these robots in real life.
 
-It is extremely easy to switch between these two. However, there are some subtle
-differences one should keep in mind, which arise due to the accompanying switch
-between non-real time behaviour (in simulation), and real-time behaviour (in real life).
+It is easy to switch between these two (see :doc:`simwithreal`). However, there are some
+subtle differences one should keep in mind, which arise due to the accompanying switch
+between non-real-time behaviour (in simulation), and real-time behaviour (with real
+robots).
 
 
-Simulation is stepped in ``append_desired_action()``
-========================================================
+Simulation is Stepped in ``append_desired_action()``
+====================================================
 
 The simulation is explicitly stepped in the ``append_desired_action()``
 method: this is because the simulation doesn't exhibit real-time
@@ -26,43 +28,44 @@ continue to move and will repeat the last action if no new action is provided in
 
 .. _`No waiting for future time steps`:
 
-No waiting for future time steps
-======================================
+No Waiting for Future Time Steps
+================================
 
 On the real robot, it is possible to pass a time index that lies in the future
-and most methods of the `robot_interfaces::RobotFrontend`_ will simply block and wait until this
-time step is reached.  The simulation, however, is not running asynchronously
-but is actively stepped every time ``append_desired_action()`` is called.
-Therefore the behaviour of waiting for a time step is not supported.  Instead,
-passing a time index that lies in the future will result in an error.
+and most methods of the :cpp:class:`robot_interfaces::RobotFrontend` will simply block
+and wait until this time step is reached.  The simulation, however, is not running
+asynchronously but is actively stepped every time ``append_desired_action()`` is called.
+Therefore the behaviour of waiting for a time step is not supported.  Instead, passing a
+time index that lies in the future will result in an error.
 
 
 No Time Series in SimFinger
-==============================
+===========================
 
-The `robot_interfaces`_ package makes use of time series for observations,
-actions, etc.  This means all data of the last few time steps is available.  One
-could, for example do the following to determine how the state of the robot
-changed:
+The :doc:`robot_interfaces <robot_interfaces:index>` package makes use of time series
+for observations, actions, etc.  This means all data of the last few time steps is
+available.  One could, for example do the following to determine how the state of the
+robot changed:
 
 .. code-block:: python
 
     previous_observation = frontend.get_observation(t - 1)
     current_observation = frontend.get_observation(t)
 
-The ``SimFinger`` class does not implement a time series, so it only provides
-the observation of the current time step ``t``.  Passing any other value for
-``t`` will result in an error.
+The ``SimFinger``:class:`~trifinger_simulation.sim_finger.SimFinger` class does not
+implement a time series, so it only provides the observation of the current time step
+``t``.  Passing any other value for ``t`` will result in an error.
 
 
-API-differences with `robot_interfaces::RobotFrontend`_
-=========================================================
+API-differences with robot_interfaces::RobotFrontend
+====================================================
 
-Our goal is to provide the same API in ``SimFinger`` as in ``RobotFrontend`` to
-make transition between simulation and real robot easy.  There are a few
-differences, though.
+Our goal is to provide the same API in
+:class:`~trifinger_simulation.sim_finger.SimFinger` as in ``RobotFrontend`` to make
+transition between simulation and real robot easy.  There are a few differences, though.
 
-Currently ``SimFinger`` supports the following methods:
+Currently :class:`~trifinger_simulation.sim_finger.SimFinger` supports the following
+methods:
 
 - ``append_desired_action()``
 - ``get_observation()``
@@ -77,6 +80,3 @@ The following methods are not supported:
   simulation, so this method is omitted to avoid confusion.
 - ``wait_until_timeindex()``:  In general the process of waiting for a specific
   time step is not supported, see :ref:`No waiting for future time steps`.
-
-.. _`robot_interfaces::RobotFrontend`: https://github.com/open-dynamic-robot-initiative/robot_interfaces/blob/master/include/robot_interfaces/robot_frontend.hpp
-.. _`robot_interfaces`: https://github.com/open-dynamic-robot-initiative/robot_interfaces/blob/master/include/robot_interfaces/

docs/simreal/simwithreal.rst

@@ -1,72 +1,63 @@
-************************************************
-Simulation vs Real Robot in trifinger_simulation
-************************************************
+********************
+Real Robot Interface
+********************
 
-We have designed the entire `trifinger_simulation` package with the
-aim of making it possible to seamlessly transition to our software for
-interfacing with these robots in the real world, to the extent of making
-this transition pretty much plug and play: depending on whether you want
-to create an instance of a simulated robot or a
-real robot, which you would like to use in a gym environment for learning, or for
-optimal control, or just to play around in by sending some crazy random commands.
+The simulation API is designed with the aim of making it easy to transition to the
+interface of the real robots.
+Below, we describe two different ways of switching between simulated and real robot:
 
-To give a very simple example of this, consider sending some control commands to
-the TriFinger,
+1. Switching between :class:`~trifinger_simulation.sim_finger.SimFinger` and
+   :class:`~trifinger_simulation.real_finger.RealFinger`
+2. Using the real-robot interface and replacing the hardware back end with the
+   simulation.
+
+Note also, that the interface of :class:`~trifinger_simulation.sim_finger.SimFinger` is
+designed to be as similar as possible to the real-robot front end, so even switching
+between the two should be relatively easy.
+
+
+RealRobot Wrapper
+=================
+
+The :class:`~trifinger_simulation.real_finger.RealFinger` class provides a wrapper
+around the real-robot interface which can be used as a drop-in replacement for
+:class:`~trifinger_simulation.sim_finger.SimFinger`.
+
+Simple example, sending control commands to the TriFinger:
 
 .. code-block:: python
 
     from trifinger_simulation import sim_finger, real_finger
 
     if use_real == True:
-        # to know what this robot is, look at the example below
-        robot = sim_finger.RealFinger(finger_type)
+        robot = real_finger.RealFinger(finger_type)
     else:
-        robot = real_finger.SimFinger(finger_type)
+        robot = sim_finger.SimFinger(finger_type)
 
     def step(action):
         for _ in range(steps_per_control):
             t = robot.append_desired_action(action)
             observation = robot.get_observation()
 
-As you can see from the example above, you can control the TriFinger in the
-same way irrespective of whether its a simulated or real. You can see an example
-of this usage in our `TriFingerReach environment <https://github.com/open-dynamic-robot-initiative/trifinger_simulation/blob/master/trifinger_simulation/gym_wrapper/envs/trifinger_reach.py>`_.
-
-The ``RealFinger`` class exposes analogous methods to interact with the real robot as the ones
-for ``SimFinger``. Inside ``RealFinger``, the robot actually gets created like this:
-
-.. code-block:: python
-
-    import robot_interfaces
-    import robot_fingers
-
-    robot_config_path = "path_to_the_config_yml_of_the_desired_robot_type"
-
-    robot_data = robot_interfaces.trifinger.SingleProcessData()
+You can see an example of this usage in our :doc:`TriFingerReach environment
+<src_trifinger_reach-py>`.
 
-    robot_backend = robot_fingers.create_trifinger_backend(
-                robot_data, robot_config_path)
-    robot = robot_interfaces.trifinger.Frontend(robot_data)
 
 .. note::
 
-    In order to use the ``RealFinger`` class, you would need to install additional packages like
-    `robot_interfaces`_ and `robot_fingers`_ as you can see in the example above. These packages are
-    not a part of the `trifinger_simulation conda environment`_. Instructions on how to install
-    these packages will follow soon in the :ref:`colcon` section.
+    In order to use the ``RealFinger`` class, you would need additional packages from
+    the TriFinger software bundle.  See :ref:`colcon`.
 
-.. note:: 
 
-    If at this point, you are interested in exploring our software interface for the
-    real robot, you can head over to the frontend of this interface to check out
-    the exposed methods in the `RobotFrontend`_,
-    and check out some demos for controlling a real robot in `here <https://github.com/open-dynamic-robot-initiative/robot_fingers/tree/master/demos>`_.
 
-In addition, you can also access the complete API of interacting with the real robot (the `RobotFrontend`_ mentioned
-in the note above) with this simulation. Head over to the next section, :ref:`robot_interfaces with Simulation` to know how to do this.
+Real Robot Front End with Simulation Back End
+=============================================
 
+The :doc:`robot_fingers <robot_fingers:index>` package provides an
+:doc:`robot_interfaces <robot_interfaces:index>`-based interface to the hardware of the
+real TriFinger robots.
 
-.. _`RobotFrontend`: https://github.com/open-dynamic-robot-initiative/robot_interfaces/blob/master/include/robot_interfaces/robot_frontend.hpp
-.. _`robot_interfaces`: https://github.com/open-dynamic-robot-initiative/robot_interfaces/blob/master/
-.. _`robot_fingers`: https://github.com/open-dynamic-robot-initiative/robot_fingers
-.. _`trifinger_simulation conda environment`: https://github.com/open-dynamic-robot-initiative/trifinger_simulation/blob/master/environment.yml
+It is possible to use the front end of the real-robot interface but with the simulation
+plugged in as back end.  This allows using the exact same code for simulation and real
+robot.  For more information on this, see :ref:`robot_fingers:simulation_backend` in the
+``robot_fingers`` documentation.

docs/simreal/src_trifinger_reach-py.rst

@@ -0,0 +1,7 @@
+:orphan:
+
+***************************************
+Example: TriFingerReach Gym Environment
+***************************************
+
+.. literalinclude:: ../../trifinger_simulation/gym_wrapper/envs/trifinger_reach.py