Add example notebooks in documentation

[flferretti]

This pull requests add the example notebooks in the documentation when rendered by Sphinx.

---

📚 Documentation preview 📚: https://jaxsim--187.org.readthedocs.build//187/

[flferretti]

It looks like when executing the notebook PD_controller it is complaining that it cannot find xvfb, even if I install ipyvirtualdisplay, which should install it as per https://conda-metadata-app.streamlit.app/?q=conda-forge%2Flinux-64%2Fpyvirtualdisplay-3.0-py39hf3d152e_3.tar.bz2. I was thinking if using MUJOCO_GL=osmesa instead of egl after installing mesalib could work or I need to go towards other directions. What do you think @traversaro?

[traversaro]

Which platform are you targeting? MUJOCO_GL=osmesa should work but it is not hardware accelerated, but if you do not need to generate a lot of images/video I guess it is ok. MUJOCO_GL=egl should work, but requires some hacks (i.e. the one in https://github.com/google-deepmind/mujoco/blame/main/mjx/tutorial.ipynb#L66-L119) on colab as the nvidia drivers are missing some files (in particular the egl .icd file).

[flferretti]

Which platform are you targeting? MUJOCO_GL=osmesa should work but it is not hardware accelerated, but if you do not need to generate a lot of images/video I guess it is ok. MUJOCO_GL=egl should work, but requires some hacks (i.e. the one in https://github.com/google-deepmind/mujoco/blame/main/mjx/tutorial.ipynb#L66-L119) on colab as the nvidia drivers are missing some files (in particular the egl .icd file).

It should be ubuntu-22.04 as per .readthedocs.yml. I'll try with the workaround you mentioned, thanks!

[flferretti]

I had no luck using egl, as even installing xvfb with apt, it still complained about a missing package:

FileNotFoundError: [Errno 2] No such file or directory: 'Xvfb'

Trying with mesalib leads to a strange KeyboardInterrupt:

---------------------------------------------------------------------------
KeyboardInterrupt                         Traceback (most recent call last)
Cell In[6], line 18
      4     data, integrator_state = js.model.step(
      5         dt=dt,
      6         model=model,
   (...)
     11         link_forces=None,
     12     )
     14     mj_model_helper.set_joint_positions(
     15         positions=data.joint_positions(), joint_names=model.joint_names()
     16     )
---> 18     recorder.record_frame(camera_name="cartpole_camera")
     20 media.show_video(recorder.frames, fps=1 / dt)
     21 recorder.frames = []

File ~/checkouts/readthedocs.org/user_builds/jaxsim/conda/187/lib/python3.11/site-packages/jaxsim/mujoco/visualizer.py:78, in MujocoVideoRecorder.record_frame(self, camera_name)
     75 """Stores a frame in the buffer."""
     76 camera_name = camera_name or "track"
---> 78 frame = self.render_frame(camera_name=camera_name)
     79 self.frames.append(frame)

File ~/checkouts/readthedocs.org/user_builds/jaxsim/conda/187/lib/python3.11/site-packages/jaxsim/mujoco/visualizer.py:72, in MujocoVideoRecorder.render_frame(self, camera_name)
     69 mujoco.mj_forward(self.model, self.data)
     70 self.renderer.update_scene(data=self.data, camera=camera_name)
---> 72 return self.renderer.render()

File ~/checkouts/readthedocs.org/user_builds/jaxsim/conda/187/lib/python3.11/site-packages/mujoco/renderer.py:244, in Renderer.render(self, out)
    242   np.copyto(self._scene.flags, original_flags)
    243 else:
--> 244   _render.mjr_readPixels(out, None, self._rect, self._mjr_context)
    246 out[:] = np.flipud(out)
    248 return out

KeyboardInterrupt: 

Check 649944a

[diegoferigo]

Thank you! Is there any reason why the functions e.g. in https://jaxsim--187.org.readthedocs.build/187/modules/_autosummary/jaxsim.api.model.html are not clickable? It's not a big deal, the website is still quite rough, I don't mind if something is not yet working as expected.

Can we remove the following duplication in the index? (again, not necessarily in this PR if you want to move it forward).

Curiosity: how did you eventually solve the problem on the rendering? With mesalib?

[flferretti]

Thank you! Is there any reason why the functions e.g. in https://jaxsim--187.org.readthedocs.build/187/modules/_autosummary/jaxsim.api.model.html are not clickable? It's not a big deal, the website is still quite rough, I don't mind if something is not yet working as expected.

I'm not sure, but we can deal with that in a different PR.

Can we remove the following duplication in the index? (again, not necessarily in this PR if you want to move it forward).

It's not duplicated. The outer level is a sphinx-gallery item, while the inner level is a rst conversion from the examples` README. If you don't like it, I can remove it.

Curiosity: how did you eventually solve the problem on the rendering? With mesalib?

EGL requires a DISPLAY environment variable set, so I could either use the same approach used for Colab or just use osmesa. The problem of the KeyboardInterrupt was due to the cell execution reaching timeout. I can eventually unify the logic together with the one used in Google Colab

[diegoferigo]

As you prefer, not blocking the merge since you already dedicate enough time to make it work as it is right now. Feel free to merge as it is.