Merge pull request #124 from ami-iit/update_docs

Update documentation to the latest API

.github/workflows/ci_cd.yml

@@ -92,7 +92,7 @@ jobs:
       - name: Document installed pip packages
         shell: bash
         run: pip list --verbose
-      
+
       - name: Import the package
         run: python -c "import jaxsim"
 

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2022, Artificial and Mechanical Intelligence 
+Copyright (c) 2022, Artificial and Mechanical Intelligence
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

docs/conf.py

@@ -4,23 +4,13 @@
 
 from pkg_resources import get_distribution
 
+if os.environ.get("READTHEDOCS"):
+    checkout_name = os.path.basename(os.path.dirname(os.path.realpath(__file__)))
+    os.environ["CONDA_PREFIX"] = os.path.realpath(
+        os.path.join("..", "..", "conda", checkout_name)
+    )
 
-def _add_annotations_import(path):
-    with open(path, "r+") as f:
-        contents = f.read()
-        if not contents.startswith("from __future__ import annotations"):
-            f.seek(0, 0)
-            f.write("from __future__ import annotations  " + contents)
-
-
-def _recursive_add_annotations_import():
-    for path, _, files in os.walk("../jaxsim/"):
-        for file in [f for f in files if f.endswith(".py")]:
-            _add_annotations_import(os.path.join(path, file))
-
-
-if "READTHEDOCS" in os.environ:
-    _recursive_add_annotations_import()
+import jaxsim
 
 # -- Version information
 
@@ -58,13 +48,14 @@ def _recursive_add_annotations_import():
     "sphinx_autodoc_typehints",
     "sphinx_multiversion",
     "enum_tools.autoenum",
+    "sphinx_design",
 ]
 
 # -- Options for intersphinx extension
 
 language = "en"
 
-html_theme = "sphinx_rtd_theme"
+html_theme = "sphinx_book_theme"
 
 templates_path = ["_templates"]
 

docs/guide/install.rst

@@ -6,12 +6,12 @@ Installation
 Prerequisites
 -------------
 
-JAXsim requires Python 3.11 or later. 
+JAXsim requires Python 3.11 or later.
 
 Basic Installation
 ------------------
 
-You can install the project with using `conda`_: 
+You can install the project with using `conda`_:
 
 .. code-block:: bash
 

docs/index.rst

@@ -3,30 +3,68 @@ JAXsim
 
 A scalable physics engine and multibody dynamics library implemented with JAX. With JIT batteries 🔋
 
-.. warning::
-    This project is still experimental, APIs could change without notice.
-
 .. note::
     This simulator currently focuses on locomotion applications. Only contacts with ground are supported.
 
 Features
 --------
 
-- Physics engine in reduced coordinates implemented with `JAX <https://github.com/google/jax/>`_ in Python.
-- JIT compilation of Python code for increased performance.
-- Transparent support to execute logic on CPUs, GPUs, and TPUs.
-- Parallel multi-body simulations on hardware accelerators for significantly increased throughput.
-- Support for SDF models (and, upon conversion, URDF models).
-- Collision detection between bodies and uneven ground surface.
-- Soft contacts model supporting full friction cone and sticking / slipping transition.
-- Complete support for inertial properties of rigid bodies.
-- Revolute, prismatic, and fixed joints support.
-- Integrators: forward Euler, semi-implicit Euler, Runge-Kutta 4.
-- High-level classes for object-oriented programming.
-- High-level classes to compute multi-body dynamics quantities from simulation state.
-- High-level classes wrapping the low-level functional RBDAs with support of `multiple velocities representations <https://research.tue.nl/en/publications/multibody-dynamics-notation-version-2>`_.
-- Default validation of JAX pytrees to prevent JIT re-compilations.
-- Preliminary support for automatic differentiation of RBDAs.
+.. grid::
+
+   .. grid-item::
+      :columns: 12 12 12 6
+
+      .. card:: Performance
+         :class-card: sd-border-0
+         :shadow: none
+         :class-title: sd-fs-5
+
+         .. div:: sd-font-normal
+
+            Physics engine in reduced coordinates implemented with `JAX <https://github.com/google/jax/>`_.
+            Compatibility with JIT compilation for increased performance and transparent support to execute logic on CPUs, GPUs, and TPUs.
+            Parallel multi-body simulations on hardware accelerators for significantly increased throughput
+
+   .. grid-item::
+      :columns: 12 12 12 6
+
+      .. card:: Model Parsing
+         :class-card: sd-border-0
+         :shadow: none
+         :class-title: sd-fs-5
+
+         .. div:: sd-font-normal
+
+            Support for SDF models (and, upon conversion, URDF models). Revolute, prismatic, and fixed joints supported.
+
+   .. grid-item::
+      :columns: 12 12 12 6
+
+      .. card:: Automatic Differentiation
+         :class-card: sd-border-0
+         :shadow: none
+         :class-title: sd-fs-5
+
+         .. div:: sd-font-normal
+
+            Support for automatic differentiation of rigid body dynamics algorithms (RBDAs) for model-based robotics research.
+            Soft contacts model supporting full friction cone and sticking / slipping transition.
+
+   .. grid-item::
+      :columns: 12 12 12 6
+
+      .. card:: Complex Dynamics
+         :class-card: sd-border-0
+         :shadow: none
+         :class-title: sd-fs-5
+
+         .. div:: sd-font-normal
+
+            JAXsim provides a variety of integrators for the simulation of multibody dynamics, including RK4, Heun, Euler, and more.
+            Support of `multiple velocities representations <https://research.tue.nl/en/publications/multibody-dynamics-notation-version-2>`_.
+
+
+----
 
 .. toctree::
   :hidden:
@@ -37,17 +75,10 @@ Features
 
 .. toctree::
   :hidden:
-  :maxdepth: 2
+  :maxdepth: 1
   :caption: JAXsim API
 
-  modules/high_level
-  modules/math
-  modules/parsers
-  modules/physics
-  modules/simulation
-  modules/typing
-  modules/utils
-
+  modules/index
 
 Examples
 --------
@@ -73,23 +104,6 @@ Here below we summarize the differences between the projects:
 - Contrarily to brax, JAXsim only supports collision detection between bodies and a compliant ground surface.
 - The RBDAs of JAXsim support automatic differentiation, but this functionality has not been thoroughly tested.
 
-Contributing
-------------
-
-Pull requests are welcome. 
-For major changes, please open an issue first to discuss what you would like to change.
-
-Citing
-------
-
-.. code-block:: bibtex
-
-    @software{ferigo_jaxsim_2022,
-      author = {Diego Ferigo and Silvio Traversaro and Daniele Pucci},
-      title = {{JAXsim}: A Physics Engine in Reduced Coordinates and Multibody Dynamics Library for Control and Robot Learning},
-      url = {http://github.com/ami-iit/jaxsim},
-      year = {2022},
-    }
 
 People
 ------

docs/modules/api.rst

@@ -0,0 +1,68 @@
+Functional API
+==============
+
+.. currentmodule:: jaxsim.api
+
+Model
+~~~~~
+
+.. automodule:: jaxsim.api.model
+    :members:
+
+Data
+~~~~
+
+.. automodule:: jaxsim.api.data
+    :members:
+
+Contact
+~~~~~~~
+
+.. automodule:: jaxsim.api.contact
+    :members:
+
+KinDynParameters
+~~~~~~~~~~~~~~~~
+
+.. automodule:: jaxsim.api.kin_dyn_parameters
+    :members:
+
+Joint
+~~~~~
+
+.. automodule:: jaxsim.api.joint
+    :members:
+
+Link
+~~~~~
+.. automodule:: jaxsim.api.link
+    :members:
+
+CoM
+~~~
+.. automodule:: jaxsim.api.com
+    :members:
+
+ODE Data
+~~~~~~~~
+
+.. automodule:: jaxsim.api.ode_data
+    :members:
+
+.. automodule:: jaxsim.api.ode
+    :members:
+
+References
+~~~~~~~~~~
+
+.. automodule:: jaxsim.api.references
+    :members:
+
+Common
+~~~~~~
+
+.. autoflag:: jaxsim.api.common.VelRepr
+    :members:
+
+.. autoclass:: jaxsim.api.common.ModelDataWithVelocityRepresentation
+    :members:

docs/modules/index.rst

@@ -0,0 +1,19 @@
+Public API
+==========
+
+.. _modules:
+
+Modules
+-------
+
+.. toctree::
+    :maxdepth: 1
+
+    api
+    integrators
+    math
+    mujoco
+    parsers
+    rbda
+    typing
+    utils

docs/modules/integrators.rst

@@ -0,0 +1,23 @@
+Integrators
+===========
+
+.. currentmodule:: jaxsim.integrators
+
+
+Common
+~~~~~~
+
+.. automodule:: jaxsim.integrators.common
+    :members:
+
+Fixed Step
+~~~~~~~~~~
+
+.. automodule:: jaxsim.integrators.fixed_step
+    :members:
+
+Variable Step
+~~~~~~~~~~~~~
+
+.. automodule:: jaxsim.integrators.variable_step
+    :members:

docs/modules/math.rst

@@ -1,13 +1,9 @@
-Math 
+Math
 ====
 
 .. currentmodule:: jaxsim.math
-
-.. automodule:: jaxsim.math.adjoint
-    :members:
-    :undoc-members:
 
-.. automodule:: jaxsim.math.conv
+.. automodule:: jaxsim.math.adjoint
     :members:
     :undoc-members:
 
@@ -19,14 +15,6 @@ Math
     :members:
     :undoc-members:
 
-.. automodule:: jaxsim.math.joint
-    :members:
-    :undoc-members:
-
-.. automodule:: jaxsim.math.plucker
-    :members:
-    :undoc-members:
-
 .. automodule:: jaxsim.math.quaternion
     :members:
     :undoc-members: