diff --git a/docs/source/conf.py b/docs/source/conf.py index 36f18b9..daeea7c 100644 --- a/docs/source/conf.py +++ b/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" diff --git a/docs/source/index.rst b/docs/source/index.rst index 4ffcf4b..0641974 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,7 +6,7 @@ pyroboplan This library extensively uses the `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 diff --git a/docs/source/motion_planning.rst b/docs/source/motion_planning.rst index cea992c..b4939e9 100644 --- a/docs/source/motion_planning.rst +++ b/docs/source/motion_planning.rst @@ -50,7 +50,10 @@ Some tools like the `MoveIt Setup Assistant `_ contains several tools that abstract away such common Pinocchio operations for motion planning. +The :examples:`Introduction to Pinocchio examples folder ` includes code examples for robot models that are manually created and automatically imported from URDF. + +Additionally, the `pyroboplan.core module `_ contains several tools that abstract away such common Pinocchio operations for motion planning. +One example can be found :examples:`here `. .. 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 `_ contains implementations for IK solvers. +You can also try running the :examples:`differential IK example `. .. 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 `_ contains implementations for motion planners. +You can also try running the :examples:`RRT example ` and :examples:`Cartesian planning example `. .. 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 `_ contains trajectory generation implementations. +You can also try running the :examples:`trajectory generation example `. .. image:: _static/images/trajectory_generation.png :width: 720 diff --git a/examples/example_cartesian_path.py b/examples/example_cartesian_path.py index 2fd757f..d8730ae 100644 --- a/examples/example_cartesian_path.py +++ b/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, diff --git a/examples/example_collision_along_path.py b/examples/example_collision_along_path.py index c36f632..644c9b3 100644 --- a/examples/example_collision_along_path.py +++ b/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 diff --git a/examples/example_differential_ik.py b/examples/example_differential_ik.py index 31dd906..4424b2b 100644 --- a/examples/example_differential_ik.py +++ b/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 diff --git a/examples/example_rrt.py b/examples/example_rrt.py index 6bdfa7e..e69f785 100644 --- a/examples/example_rrt.py +++ b/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 diff --git a/examples/example_trajectory.py b/examples/example_trajectory.py index 3ef314e..4f5f324 100644 --- a/examples/example_trajectory.py +++ b/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