Add example notebooks in documentation

ami-iit · Jun 21, 2024 · ab08085 · ab08085
1 parent 99f84fc
commit ab08085
Show file tree

Hide file tree

Showing 4 changed files with 78 additions and 2 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -48,6 +48,9 @@
     "sphinx_autodoc_typehints",
     "sphinx_multiversion",
     "enum_tools.autoenum",
+    "myst_nb",
+    "sphinx_gallery.gen_gallery",
+    "sphinxcontrib.collections",
     "sphinx_design",
 ]
 
@@ -72,3 +75,30 @@
 autosummary_generate = False
 
 epub_show_urls = "footnote"
+
+# -- Options for sphinx-collections
+
+collections = {
+    "examples": {"driver": "copy_folder", "source": "../examples/", "ignore": "assets"}
+}
+
+# -- Options for sphinx-gallery ----------------------------------------------
+
+sphinx_gallery_conf = {
+    "examples_dirs": "_collections/examples",
+    "gallery_dirs": ("_collections/generated_examples/"),
+    "ignore_pattern": r"_test\.py",
+    "doc_module": "jaxsim",
+    "backreferences_dir": os.path.join("modules", "generated"),
+}
+
+# -- Options for myst -------------------------------------------------------
+myst_enable_extensions = [
+    "amsmath",
+    "dollarmath",
+]
+nb_execution_mode = "force"
+nb_execution_allow_errors = False
+nb_render_image_options = {}
+
+source_suffix = [".rst", ".md", ".ipynb"]
diff --git a/docs/examples.rst b/docs/examples.rst
@@ -0,0 +1,42 @@
+.. _examples:
+
+Example Notebooks
+=================
+
+.. toctree::
+    :glob:
+    :hidden:
+    :maxdepth: 1
+
+    _collections/examples/README.md
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="Parallel Simulation.">
+
+.. only:: html
+
+    :doc:`_collections/examples/Parallel_computing`
+
+    </div>
+
+
+.. raw:: html
+
+      <div class="sphx-glr-thumbnail-title">Parallel Simulation</div>
+    </div>
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="PD Controller.">
+
+.. only:: html
+
+    :doc:`_collections/examples/PD_Controller`
+
+    </div>
+
+.. raw:: html
+
+    <div class="sphx-glr-thumbnail-title">PD Controller</div>
+</div>
diff --git a/docs/index.rst b/docs/index.rst
@@ -68,11 +68,11 @@ Features
 
 .. toctree::
   :hidden:
-  :maxdepth: 1
-  :caption: User Guide
 
   guide/install
 
+  examples
+
 .. toctree::
   :hidden:
   :maxdepth: 1

diff --git a/environment.yml b/environment.yml
@@ -38,13 +38,15 @@ dependencies:
   - filecache
   - filelock
   - jinja2
+  - myst-nb
   - pip
   - sphinx
   - sphinx-autodoc-typehints
   - sphinx-book-theme
   - sphinx-copybutton
   - sphinx-design
   - sphinx_fontawesome
+  - sphinx-gallery
   - sphinx-jinja2-compat
   - sphinx-multiversion
   - sphinx_rtd_theme
@@ -53,3 +55,5 @@ dependencies:
   # Other dependencies for GitHub Codespaces
   # ========================================
   - ipython
+  - pip:
+    - sphinx-collection  # TODO (flferretti): PR to conda-forge