Update website

docs/sphinx/breathe/core.rst

@@ -17,5 +17,7 @@ Core
 
 .. doxygenenum:: scenario::core::JointControlMode
 
+.. doxygenenum:: scenario::core::JointType
+
 .. doxygenfile:: core/utils/utils.h
-   :project: scenario
+   :project: scenario

docs/sphinx/breathe/gazebo.rst

@@ -29,9 +29,6 @@ Gazebo
 .. doxygenclass:: scenario::controllers::UseScenarioModel
    :members:
 
-.. doxygenclass:: scenario::controllers::UseScenarioModel
-   :members:
-
 .. doxygenclass:: scenario::controllers::SetJointReferences
    :members:
 

docs/sphinx/getting_started/gym-ignition.rst

@@ -27,6 +27,12 @@ Beyond the abstractions provided by ScenarIO, gym-ignition introduces the follow
   Refer to :py:class:`~gym_ignition.rbd.idyntree.inverse_kinematics_nlp.InverseKinematicsNLP` and
   :py:class:`~gym_ignition.rbd.idyntree.kindyncomputations.KinDynComputations` for more details.
 
+.. tip::
+
+    If you want to learn more about ``iDynTree``, the two classes we mainly use are ``iDynTree::KinDynComputations`` (`docs <https://robotology.github.io/idyntree/master/classiDynTree_1_1KinDynComputations.html>`__) and ``iDynTree::InverseKinematics`` (`docs <https://robotology.github.io/idyntree/master/classiDynTree_1_1InverseKinematics.html>`__).
+
+    The theory and notation is summarized in `Multibody dynamics notation <https://pure.tue.nl/ws/portalfiles/portal/139293126/A_Multibody_Dynamics_Notation_Revision_2_.pdf>`_.
+
 You can find demo environments created with ``gym-ignition`` in the
 `gym_ignition_environments <https://github.com/robotology/gym-ignition/blob/master/python/gym_ignition_environments>`_ folder.
 These examples show how to structure a new standalone Python package containing the environment with your robots.

docs/sphinx/getting_started/scenario.rst

@@ -1,7 +1,7 @@
 .. _getting_started_scenario:
 
-ScenarI/O
-=========
+ScenarIO
+========
 
 In this getting started section we show how to use the Gazebo ScenarIO library to simulate a pendulum system.
 We will use the models of the ground plane and the pendulum stored in the repository

docs/sphinx/index.rst

@@ -1,40 +1,27 @@
-.. _what_is_gym_ignition:
+.. _scenario_and_gym_ignition:
 
-What is gym-ignition?
-=====================
+ScenarIO and gym-ignition
+=========================
 
-**gym-ignition is a framework to create reproducible robotics environments for reinforcement learning research.**
+This project targets both *control* and *robot learning* research domains:
 
-The aims of the project are the following:
-
-- Provide unified APIs for interfacing with both simulated and real robots.
-- Implement the simulation backend interfacing with the Ignition Gazebo simulator.
-- Enable a seamless switch of all the physics engines supported by Ignition Gazebo.
-- Guarantee the reproducibility and the scalability of the simulations by using the simulator as a library, without
-  relying on any network transport.
-- Simplify the development of OpenAI Gym environments for robot learning research.
-
-**gym-ignition** targets both *control* and *robot learning* research domains:
-
-- Researchers in robotics and control can simulate their robots with familiar tools like Gazebo and URDF,
+- Researchers in robotics and control can simulate their robots with familiar tools like Gazebo and URDF/SDF,
   without the need to rely on any middleware.
 - Researchers in robot learning can quickly develop new robotic environments that can scale to hundreds of parallel instances.
 
-To know more about why we started developing gym-ignition, why we selected Ignition Gazebo for our simulations,
-and what are our long-term goals, visit the :ref:`Motivations <motivations>` page.
+We provide two related subprojects to each of these categories:
 
-We are building an entire ecosystem around gym-ignition, if you're interested have a look to the other projects:
+1. **ScenarIO** provides APIs to interface with the robots.
+2. **gym-ignition** helps structuring environments compatible with OpenAI Gym,
+   while minimizing boilerplate code and providing common rigid-body dynamics utilities.
 
-.. list-table::
-    :header-rows: 1
-    :align: center
+Check the sections :ref:`What is ScenarIO <what_is_scenario>` and
+:ref:`What is gym-ignition <what_is_gym_ignition>` for more details,
+and visit :ref:`Motivations <motivations>` for an extended overview.
+
+For a quick practical introduction, visit the :ref:`Getting Started <getting_started_scenario>` page.
 
-    * - ScenarI/O and ``gym_ignition``
-      - Robot Models
-      - Ignition Plugins
-    * - `robotology/gym-ignition <https://github.com/robotology/gym-ignition>`_
-      - `robotology/gym-ignition-models <https://github.com/robotology/gym-ignition-models>`_
-      - `dic-iit/gazebo-scenario-plugins <https://github.com/dic-iit/gazebo-scenario-plugins>`_
+If you use this project for your research, please check the FAQ about :ref:`how to give credit <faq_citation>`.
 
 .. list-table::
 
@@ -49,14 +36,22 @@ We are building an entire ecosystem around gym-ignition, if you're interested ha
 .. toctree::
    :hidden:
    :maxdepth: 1
-   :caption: Motivations
+   :caption: What
+
+   what/what_is_scenario
+   what/what_is_gym_ignition
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: Why
 
-   motivations/why_gym_ignition
+   motivations/motivations
 
 .. toctree::
    :hidden:
    :maxdepth: 1
-   :caption: Installation
+   :caption: Installation (How)
 
    installation/support_policy
    installation/stable
@@ -75,7 +70,7 @@ We are building an entire ecosystem around gym-ignition, if you're interested ha
 .. toctree::
    :hidden:
    :maxdepth: 2
-   :caption: ScenarI/O C++ API:
+   :caption: ScenarIO C++ API:
 
    breathe/core
    breathe/gazebo

docs/sphinx/info/faq.rst

@@ -1,6 +1,26 @@
 FAQ
 ===
 
+.. _faq_citation:
+
+How to give credit?
+-------------------
+
+If you use **ScenarIO** or **gym-ignition** for your research,
+please cite the following reference:
+
+.. code-block:: bibtex
+   :caption: BibTeX entry
+
+   @INPROCEEDINGS{ferigo2020gymignition,
+     title={Gym-Ignition: Reproducible Robotic Simulations for Reinforcement Learning},
+     author={D. {Ferigo} and S. {Traversaro} and G. {Metta} and D. {Pucci}},
+     booktitle={2020 IEEE/SICE International Symposium on System Integration (SII)},
+     year={2020},
+     pages={885-890},
+     doi={10.1109/SII46433.2020.9025951}
+   }
+
 Interaction with Tensorflow
 ---------------------------
 

docs/sphinx/installation/developer.rst

@@ -33,20 +33,23 @@ the CMake project as follows:
 
 .. code-block:: bash
 
-    mkdir build
-    cd build
-    cmake ..
-    cmake --build .
-    cmake --build . --target install
+    cd scenario/
+    cmake -S . -B build
+    cmake --build build/
+    cmake --build build/ --target install
 
 .. note::
+
     The default install prefix of the CMake project is ``/usr/local``.
     If you want to use a different folder, pass ``-DCMAKE_INSTALL_PREFIX=/new/install/prefix`` to the first ``cmake`` command.
 
 .. attention::
-    The SWIG bindings are installed in the `site-packages <https://docs.python.org/3/install/#how-installation-works>`_ folder of the active Python interpreter.
+
+    The SWIG bindings are installed in the `site-packages <https://docs.python.org/3/install/#how-installation-works>`_
+    folder of the active Python interpreter.
     If you have an active virtual environment, it will be automatically detected.
-    Visit `FindPython3 <https://cmake.org/cmake/help/v3.12/module/FindPython3.html>`_ for more details.
+    We rely on CMake's logic for detecting Python,
+    visit `FindPython3 <https://cmake.org/cmake/help/v3.16/module/FindPython3.html>`_ for more details.
 
 .. include:: virtual_environment.rst
 
@@ -58,10 +61,18 @@ From the root of the repository:
 
 .. code-block:: bash
 
+    pip install -e scenario/
     pip install -e .
 
 The editable installation only symlinks the resources of the repository into the active Python installation.
 It allows to develop directly operating on the files of the repository and use the updated package without requiring
 to install it again.
 
+.. note::
+
+    The ``scenario`` editable installation is just a placeholder.
+    It is necessary to prevent the editable installation of ``gym-ignition`` to override the resources installed by
+    the manual CMake execution.
+    Otherwise, the ``scenar-io`` package from PyPI would be pulled, resulting with a wrong version.
+
 .. include:: system_configuration.rst

docs/sphinx/installation/nightly.rst

@@ -13,10 +13,23 @@ We publish updated nightly packages after any pull request merged in the ``devel
 PyPI Package
 ************
 
-Install the pre-release `gym-ignition <https://pypi.org/project/gym-ignition/>`_ package from PyPI:
+We provide two different packages for ScenarIO and gym-ignition.
+
+If you are interested in the ScenarIO package,
+install the `scenar-io <https://pypi.org/project/scenar-io/>`_ package from PyPI:
+
+.. code-block:: bash
+
+   pip install --pre scenar-io
+
+Instead, if you are interested in gym-ignition,
+install the `gym-ignition <https://pypi.org/project/gym-ignition/>`_ package from PyPI:
 
 .. code-block:: bash
 
-   pip install --pre gym-ignition
+   pip install --pre scenar-io gym-ignition
+
+Note that in this case, specifying also the ``scenar-io`` dependency is necessary,
+otherwise ``pip`` will pull the stable package from PyPI.
 
 .. include:: system_configuration.rst

docs/sphinx/installation/stable.rst

@@ -13,8 +13,20 @@ We publish updated stable packages after any tagged release of the ``master`` br
 PyPI Package
 ************
 
-Install the `gym-ignition <https://pypi.org/project/gym-ignition/>`_ package from PyPI:
+We provide two different packages for ScenarIO and gym-ignition.
+
+If you are interested in the ScenarIO package,
+install the `scenar-io <https://pypi.org/project/scenar-io/>`_ package from PyPI:
+
+.. code-block:: bash
+
+   pip install scenar-io
+
+Instead, if you are interested in gym-ignition,
+install the `gym-ignition <https://pypi.org/project/gym-ignition/>`_ package from PyPI:
 
 .. code-block:: bash
 
    pip install gym-ignition
+
+It will download and install also ``scenar-io`` since it depends on it.

docs/sphinx/installation/support_policy.rst

@@ -8,7 +8,7 @@ dependencies, depending on the installation type you select.
 
 The project mostly supports all the major operating systems.
 However, we are currently using and testing only GNU/Linux systems.
-We do not yet provide direct support to other operating systems.
+We do not yet provide official support to other operating systems.
 
 The table below recaps the project requirements of the :ref:`Stable <installation_stable>` and :ref:`Nightly <installation_nightly>` channels:
 
@@ -31,12 +31,12 @@ The table below recaps the project requirements of the :ref:`Stable <installatio
     Our policy is to support Ubuntu from the most recent LTS distribution, currently Ubuntu 20.04 Focal.
     We typically switch to a new LTS when the first minor release ``YY.MM.1`` is released.
 
-    The Python and compilers policies follow a similar policy, we try to keep them updated as much as
-    possible following what includes the supported LTS distribution.
+    The Python and compilers policies follow a similar approach, we try to keep them updated as much as
+    possible following what the supported LTS distribution includes.
 
 .. note::
 
-    External contributions to add the support and provide feedback of other platforms are most welcome.
+    External contributions to extend the support and provide feedback about other platforms are most welcome.
 
 .. admonition:: Fun fact
 

docs/sphinx/motivations/why_gym_ignition.rst → docs/sphinx/motivations/motivations.rst

@@ -1,12 +1,13 @@
 .. _motivations:
 
-In this section we recap the motivations behind gym-ignition.
+In this section we recap the motivations behind this project.
 Choosing the right framework for your research is often challenging and we hope to provide a broader look that could
 help deciding whether it meets your needs or not.
 
 The development of the framework is evolving quickly, and the architecture and motivations described in the
-`reference publication <https://github.com/robotology/gym-ignition#Citation>`_ are no longer accurate.
-This section provides a constantly updated description aligned with the most recent development news.
+:ref:`reference publication <faq_citation>` are becoming outdated.
+While that publication remains the reference in case you use the project for your research,
+this section provides a constantly updated description aligned with the most recent development news.
 
 .. _why_scenario:
 
@@ -36,16 +37,18 @@ it will interact either with the simulated or the real robot depending on the Sc
 .. note::
 
    The ScenarIO interface is flexible and generic.
-   Let's say you already have built your functionality with the backends we provide, and you are not happy from the performance of the simulator we used.
+   Let's say you already have built your functionality with the backends we provide,
+   and you are not happy from the performance of the simulator we used.
    You can implement your own simulation backend and run it alongside those we provide.
    The same applies to the real-time backend, in case your robot uses a custom middleware or SDK.
 
-.. tip:
+.. tip::
 
    So far, we always referred to the C++ abstraction layer provided by ScenarIO.
    The interface / implementation pattern is implemented with classic inheritance and polymorphism.
    Having such unified interface simplifies the process to expose it to other languages.
-   Thanks to SWIG, we officially provide Python bindings of ScenarIO, so that you can prototype your applications even faster!
+   Thanks to SWIG, we officially provide Python bindings of ScenarIO,
+   so that you can prototype your applications even faster!
 
 .. _why_ignition_gazebo:
 
@@ -67,7 +70,7 @@ The price to pay, instead, is that Ignition Gazebo has not yet reached feature p
 the gap is getting filled quickly.
 
 .. [*] Yes, you read correctly: *library*. Ignition Gazebo is a library.
-       A `ignition::gazebo::Server` object can be instantiated and it can be stepped programmatically from your code.
+       A ``ignition::gazebo::Server`` object can be instantiated and it can be stepped programmatically from your code.
        This type of architecture became quite popular recently because it gives you full control of the simulation.
        Ignition Gazebo, therefore, became a solution similar to the well known alternatives like ``pybullet`` and ``mujoco-py``.
 

docs/sphinx/what/what_is_gym_ignition.rst

@@ -0,0 +1,22 @@
+.. _what_is_gym_ignition:
+
+What is gym-ignition?
+=====================
+
+**gym-ignition** is a framework to create **reproducible robotics environments** for reinforcement learning research.
+
+It is based on the :ref:`ScenarIO <what_is_scenario>` project which provides the low-level APIs to interface with the Ignition Gazebo simulator.
+By default, RL environments share a lot of boilerplate code, e.g. for initializing the simulator or structuring the classes
+to expose the ``gym.Env`` interface.
+Gym-ignition provides the :py:class:`~gym_ignition.base.task.Task` and :py:class:`~gym_ignition.base.runtime.Runtime`
+abstractions that help you focusing on the development of the decision-making logic rather than engineering.
+It includes :py:mod:`~gym_ignition.randomizers` to simplify the implementation of domain randomization
+of models, physics, and tasks.
+Gym-ignition also provides powerful dynamics algorithms compatible with both fixed-base and floating-based robots by
+exploiting `iDynTree <https://github.com/robotology/idyntree/>`_ and exposing
+high-level functionalities (:py:mod:`~gym_ignition.rbd.idyntree`).
+
+Gym-ignition does not provide out-of-the-box environments ready to be used.
+Rather, its aim is simplifying and streamlining their development.
+Nonetheless, for illustrative purpose, it includes canonical examples in the
+:py:mod:`gym_ignition_environments` package.