Point to examples in docs (sea-bass#29)

docs/source/conf.py

@@ -22,6 +22,7 @@
 extensions = [
     "sphinx_rtd_theme",
     "sphinx.ext.autodoc",
+    "sphinx.ext.extlinks",
     "sphinx.ext.napoleon",
 ]
 
@@ -32,8 +33,16 @@
 templates_path = ["_templates"]
 exclude_patterns = ["build", "Thumbs.db", ".DS_Store"]
 
+# External links
+extlinks = {
+    "examples": ("https://github.com/sea-bass/pyroboplan/tree/main/examples/%s", ""),
+    "source": (
+        "https://github.com/sea-bass/pyroboplan/tree/main/src/pyroboplan/%s",
+        "",
+    ),
+}
 
-# -- Options for HTML output -------------------------------------------------
+# Options for HTML output
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "sphinx_rtd_theme"

docs/source/index.rst

@@ -6,7 +6,7 @@ pyroboplan
 This library extensively uses the `Pinocchio <https://github.com/stack-of-tasks/pinocchio>`_ Python bindings for modeling robot kinematics and dynamics.
 
 Note the **educational** in this library description.
-It is not designed for performance, but rather to teach newcomers the fundamentals of motion planning in an easy-to-use environment.
+It is not designed for performance, but rather to teach newcomers the fundamentals of motion planning in an easy-to-use environment with :examples:`many examples <>`.
 
 .. image:: _static/gifs/pyroboplan_rrt_traj.gif
   :width: 640

docs/source/motion_planning.rst

@@ -50,7 +50,10 @@ Some tools like the `MoveIt Setup Assistant <https://moveit.picknik.ai/main/doc/
         model, data, collision_model, collision_data, q, False,
     )
 
-The `pyroboplan.core module <api/pyroboplan.core.html>`_ contains several tools that abstract away such common Pinocchio operations for motion planning.
+The :examples:`Introduction to Pinocchio examples folder <intro_pinocchio>` includes code examples for robot models that are manually created and automatically imported from URDF.
+
+Additionally, the `pyroboplan.core module <api/pyroboplan.core.html>`_ contains several tools that abstract away such common Pinocchio operations for motion planning.
+One example can be found :examples:`here <example_collision_along_path.py>`.
 
 .. image:: _static/images/collision_checking.png
     :width: 600
@@ -73,6 +76,7 @@ However, for most robotics applications, we rely on **numerical methods** instea
 * Additional constraints, such as joint limits, Cartesian pose limits, or collision avoidance, are difficult to enforce analytically.
 
 The `pyroboplan.ik module <api/pyroboplan.ik.html>`_ contains implementations for IK solvers.
+You can also try running the :examples:`differential IK example <example_differential_ik.py>`.
 
 .. image:: _static/images/inverse_kinematics.png
     :width: 600
@@ -100,6 +104,7 @@ Currently, all the planners in ``pyroboplan`` (such as RRT and Cartesian interpo
 Online planning and control is often done through optimization techniques like Model Predictive Control (MPC).
 
 The `pyroboplan.planning module <api/pyroboplan.planning.html>`_ contains implementations for motion planners.
+You can also try running the :examples:`RRT example <example_rrt.py>` and :examples:`Cartesian planning example <example_cartesian_path.py>`.
 
 .. image:: _static/images/bidirectional_rrt_star.png
     :width: 600
@@ -118,6 +123,7 @@ Often, a fixed set of kinematic (position/velocity/acceleration/jerk) and dynami
 Sometimes, these limits can also be task-dependent; for example, if manipulating fragile objects or objects that cannot be placed in certain configurations (e.g., moving a glass of water without spilling).
 
 The `pyroboplan.trajectory module <api/pyroboplan.trajectory.html>`_ contains trajectory generation implementations.
+You can also try running the :examples:`trajectory generation example <example_trajectory.py>`.
 
 .. image:: _static/images/trajectory_generation.png
     :width: 720

examples/example_cartesian_path.py

@@ -1,3 +1,8 @@
+"""
+This example shows PyRoboPlan capabilities for Cartesian planning to track
+task-space, or operational space, motions with straight-line interpolation.
+"""
+
 import matplotlib.pyplot as plt
 import numpy as np
 import pinocchio
@@ -53,7 +58,6 @@
     options=DifferentialIkOptions(max_retries=5),
 )
 
-
 # Create the Cartesian Planner over the entire desired path.
 options = CartesianPlannerOptions(
     use_trapezoidal_scaling=True,

examples/example_collision_along_path.py

@@ -1,3 +1,10 @@
+"""
+This example shows PyRoboPlan capabilities around Pinocchio to import a model
+and perform collision checking along a predefined path.
+These capabilities form the basis of collision checking for validating other
+motion planning components such as inverse kinematics and path planning.
+"""
+
 import hppfcl
 import pinocchio
 from pinocchio.visualize import MeshcatVisualizer

examples/example_differential_ik.py

@@ -1,3 +1,9 @@
+"""
+This example shows PyRoboPlan capabilities for inverse kinematics (IK).
+IK defines the task of finding a set of joint positions for a robot model to
+achieve a desired target pose for a specific coordinate frame.
+"""
+
 from pinocchio.visualize import MeshcatVisualizer
 import numpy as np
 

examples/example_rrt.py

@@ -1,3 +1,8 @@
+"""
+This example shows PyRoboPlan capabilities for path planning using
+Rapidly-Expanding Random Tree (RRT) algorithm.
+"""
+
 from pinocchio.visualize import MeshcatVisualizer
 import time
 

examples/example_trajectory.py

@@ -1,3 +1,8 @@
+"""
+This example shows PyRoboPlan capabilities for trajectory generation giving
+various time scaling approaches, such as polynomial and trapezoidal velocity.
+"""
+
 import matplotlib.pyplot as plt
 import numpy as np
 from pinocchio.visualize import MeshcatVisualizer