Switch to furo Sphinx theme

haosulab · Feb 14, 2024 · 44a5237 · 44a5237
1 parent 17b8dc2
commit 44a5237
Show file tree

Hide file tree

Showing 23 changed files with 100 additions and 84 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# MPlib
+# MPlib: a Lightweight Motion Planning Library
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/haosulab/MPlib/main/docs/demo.gif">

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,3 +1,4 @@
 myst-parser
-sphinx-rtd-theme
+furo
 sphinx-copybutton
+sphinxext-opengraph
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -20,8 +20,9 @@
     "sphinx.ext.duration",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
-    "sphinx_rtd_theme",
     "myst_parser",
+    "sphinx_copybutton",
+    "sphinxext.opengraph",
 ]
 
 templates_path = ["_templates"]
@@ -31,5 +32,15 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "sphinx_rtd_theme"
+# https://pradyunsg.me/furo/customisation/
+html_theme = "furo"
+# html_theme = "sphinx_book_theme"
 html_static_path = []
+html_theme_options = {
+    # "announcement": "<em>Important</em> announcement!",
+    # Comment out for Read the Docs
+    # "top_of_page_button": "edit",
+    # "source_repository": "https://github.com/haosulab/MPlib",
+    # "source_branch": "main",
+    # "source_directory": "docs/source/",
+}
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -3,20 +3,9 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to mplib's documentation!
-=================================
-
 .. include:: ../../README.md
    :parser: myst_parser.sphinx_
 
-Planner Documentation
----------------------
-
-.. toctree::
-   :maxdepth: 1
-
-   mplib
-
 Examples
 -----------
 
@@ -31,7 +20,7 @@ API Reference
 .. toctree::
    :maxdepth: 2
 
-   pymp/index
+   reference/index
 
 Indices and tables
 ==================

diff --git a/docs/source/pymp/collision_detection/index.rst b/docs/source/pymp/collision_detection/index.rst
diff --git a/docs/source/pymp/index.rst b/docs/source/pymp/index.rst
diff --git a/docs/source/pymp/pymp.rst b/docs/source/pymp/pymp.rst
diff --git a/docs/source/reference/ArticulatedModel.rst b/docs/source/reference/ArticulatedModel.rst
@@ -0,0 +1,7 @@
+``ArticulatedModel``
+-------------------------
+
+.. autoclass:: mplib.pymp.ArticulatedModel
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/mplib.rst → docs/source/reference/Planner.rst b/docs/source/mplib.rst → docs/source/reference/Planner.rst
@@ -1,8 +1,5 @@
-Planner
-=======
-
-mplib.planner
---------------------
+``Planner``
+-------------
 
 .. automodule:: mplib.planner
    :members:

diff --git a/docs/source/reference/PlanningWorld.rst b/docs/source/reference/PlanningWorld.rst
@@ -0,0 +1,7 @@
+``PlanningWorld``
+-------------------
+
+.. autoclass:: mplib.pymp.PlanningWorld
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/pymp/collision_detection/fcl.rst → ...rce/reference/collision_detection/fcl.rst b/docs/source/pymp/collision_detection/fcl.rst → ...rce/reference/collision_detection/fcl.rst
diff --git a/docs/source/reference/collision_detection/index.rst b/docs/source/reference/collision_detection/index.rst
@@ -0,0 +1,12 @@
+collision_detection
+------------------------------------------
+
+.. automodule:: mplib.pymp.collision_detection
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. toctree::
+   :maxdepth: 2
+
+   fcl
diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst
@@ -0,0 +1,24 @@
+API Reference
+======================
+
+.. toctree::
+   :maxdepth: 2
+
+   Planner
+   ArticulatedModel
+   PlanningWorld
+
+.. toctree::
+   :maxdepth: 3
+
+   collision_detection/index
+
+.. toctree::
+   :maxdepth: 4
+
+   kinematics/index
+
+.. toctree::
+   :maxdepth: 4
+
+   planning/index
diff --git a/docs/source/reference/kinematics/index.rst b/docs/source/reference/kinematics/index.rst
@@ -0,0 +1,10 @@
+kinematics
+-------------------------------------------
+
+Kinematics submodule
+
+.. toctree::
+   :maxdepth: 3
+
+   pinocchio
+   kdl
diff --git a/docs/source/pymp/kinematics/kdl.rst → docs/source/reference/kinematics/kdl.rst b/docs/source/pymp/kinematics/kdl.rst → docs/source/reference/kinematics/kdl.rst
diff --git a/docs/source/pymp/kinematics/pinocchio.rst → ...source/reference/kinematics/pinocchio.rst b/docs/source/pymp/kinematics/pinocchio.rst → ...source/reference/kinematics/pinocchio.rst
diff --git a/docs/source/reference/planning/index.rst b/docs/source/reference/planning/index.rst
@@ -0,0 +1,9 @@
+planning
+--------------------------
+
+Planning submodule
+
+.. toctree::
+   :maxdepth: 3
+
+   ompl
diff --git a/docs/source/pymp/planning/ompl.rst → docs/source/reference/planning/ompl.rst b/docs/source/pymp/planning/ompl.rst → docs/source/reference/planning/ompl.rst
diff --git a/docs/source/tutorials/collision_avoidance.rst b/docs/source/tutorials/collision_avoidance.rst
@@ -1,4 +1,4 @@
- .. _collision_avoidance:
+.. _collision_avoidance:
 
 Collision Avoidance
 ====================
@@ -69,4 +69,4 @@ You can use  ``planner.update_attached_box()`` again to update the box once it's
 As shown in the above figure (the right one), after adding the point cloud of the blue box and attaching the red box to the ``move_group`` link, there is no collision.
 
 .. note::
-   There are also a family of update attach functions. One can attach a sphere or a general mesh. Please see the planner API for more details.
+   There are also a family of update attach functions. One can attach a sphere or a general mesh. Please see the planner API for more details.
diff --git a/docs/source/tutorials/constrained_planning.rst b/docs/source/tutorials/constrained_planning.rst
@@ -5,6 +5,7 @@ Constrained Planning
 
 .. image:: assets/constrained_planning.gif
    :width: 50%
+   :align: center
 
 This is a simple implementation of a constrained planner. It is based on OMPL's projection-based planner. Roughly, OMPL does sampling based planning and projects a joint configuration into a valid configuration using the constrained function we provide. The above gif shows the robot execute two trajectories. The first one generated with constraint that the z-axis of the endeffector pointing downwards. The second one generated without any constraints. We can see that the second trajectory tilts the endeffector sideways.
 

diff --git a/docs/source/tutorials/getting_started.rst b/docs/source/tutorials/getting_started.rst
@@ -1,4 +1,4 @@
- .. _motion_planning_getting_started:
+.. _motion_planning_getting_started:
 
 Getting Started
 ==================
@@ -38,4 +38,4 @@ To use ``mplib``, we need to first set up a planner for the robot with the follo
 
 After setting up the planner, we can use it to solve many motion planning tasks.
 
-.. [1] ``mplib`` currently only supports a single link as ``move_group``.
+.. [1] ``mplib`` currently only supports a single link as ``move_group``.
diff --git a/docs/source/tutorials/inverse_kinematics.rst b/docs/source/tutorials/inverse_kinematics.rst
@@ -1,4 +1,4 @@
- .. _inverse_kinematics:
+.. _inverse_kinematics:
 
 Inverse Kinematics
 ==================

diff --git a/docs/source/tutorials/plan_a_path.rst b/docs/source/tutorials/plan_a_path.rst
@@ -1,4 +1,4 @@
- .. _plan_a_path:
+.. _plan_a_path:
 
 Plan a Path
 ==================
@@ -9,7 +9,7 @@ In this tutorial, we will talk about how to plan paths for the agent. As shown i
 
 .. figure:: assets/RRT.gif
    :width: 320px
-   :align: left
+   :align: center
 
    plan with RRTConnect
 
@@ -34,9 +34,9 @@ The second argument is the current joint positions of all the active joints (not
 
 - ``status``: a string indicates the status:
 
-    - ``Success``: planned a path successfully.
-    - ``IK Failed``: failed to solve the inverse kinematics. This may happen when the target pose is not reachable.
-    - ``RRT Failed``: failed to find a valid path in the joint space. This may happen when there is no valid path or the task is too complicated.
+  - ``Success``: planned a path successfully.
+  - ``IK Failed``: failed to solve the inverse kinematics. This may happen when the target pose is not reachable.
+  - ``RRT Failed``: failed to find a valid path in the joint space. This may happen when there is no valid path or the task is too complicated.
 - ``position``: a NumPy array of shape :math:`(n \times m)` describes the joint positions of the waypoints. :math:`n` is the number of waypoints in the path, and each row describes a waypoint. :math:`m` is the number of active joints that affect the pose of the ``move_group`` link. For example, for our panda robot arm, each row includes the positions for the first seven joints. 
 - ``duration``: a scalar indicates the duration of the output path. ``mplib`` returns the optimal duration considering the velocity and acceleration constraints. 
 - ``time``: a NumPy array of shape :math:`(n)` describes the time step of each waypoint. The first element is equal to 0, and the last one is equal to the ``duration``. Argument ``time_step`` determines the interval of the elements.
@@ -108,6 +108,6 @@ Then, we plan and execute the motion:
 
 .. figure:: assets/screw.gif
    :width: 320px
-   :align: left
+   :align: center
 
    plan with screw motion