diff --git a/core/doc/reference.rst b/core/doc/api.rst similarity index 87% rename from core/doc/reference.rst rename to core/doc/api.rst index 04e60773..a1a47001 100644 --- a/core/doc/reference.rst +++ b/core/doc/api.rst @@ -1,7 +1,7 @@ .. _sec-api: -API ---- +API reference +------------- .. autosummary:: :toctree: _autosummary diff --git a/core/doc/concepts.rst b/core/doc/concepts.rst index f8466ae6..7465e47a 100644 --- a/core/doc/concepts.rst +++ b/core/doc/concepts.rst @@ -1,10 +1,8 @@ .. _sec-concepts: -Topic Guides +Concepts ------------ -In-depth explanation about the concepts behind the moveit task constructor framework. - .. toctree:: :maxdepth: 2 diff --git a/core/doc/howtoguides.rst b/core/doc/howto.rst similarity index 95% rename from core/doc/howtoguides.rst rename to core/doc/howto.rst index 1b58d8cd..2eb34552 100644 --- a/core/doc/howtoguides.rst +++ b/core/doc/howto.rst @@ -8,8 +8,6 @@ How-To Guides Stage Usage ----------- -Short examples on how to use the mtc stages. - .. _subsubsec-howto-alternatives: Alternatives @@ -217,9 +215,9 @@ MoveTo ^^^^^^ Use planners to compute a motion plan. -Download the full example code here: :download:`Source <./../../demo/scripts/cartesian.py>` +Download the full example code here: :download:`Source <../../demo/scripts/cartesian.py>` -.. literalinclude:: ./../../demo/scripts/cartesian.py +.. literalinclude:: ../../demo/scripts/cartesian.py :language: python :lines: 51-55 @@ -230,9 +228,9 @@ MoveRelative ^^^^^^^^^^^^ Move along a relative offset. -Download the full example code here: :download:`Source <./../../demo/scripts/cartesian.py>` +Download the full example code here: :download:`Source <../../demo/scripts/cartesian.py>` -.. literalinclude:: ./../../demo/scripts/cartesian.py +.. literalinclude:: ../../demo/scripts/cartesian.py :language: python :lines: 26-31 diff --git a/core/doc/index.rst b/core/doc/index.rst index 88eee317..c80cedc5 100644 --- a/core/doc/index.rst +++ b/core/doc/index.rst @@ -11,30 +11,20 @@ basic stages using containers, allowing for sequential as well as parallel compo For more details, please refer to the associated `ICRA 2019 publication `_. -How the documentation is organized ----------------------------------- +Organization of the documentation +--------------------------------- -- :ref:`sec-tutorials` guide you - through the initial learning process of setting up a task pipeline. - Take a look at the :ref:`first steps ` if you - are new to the moveit task constructor. - -- :ref:`sec-concepts` discuss the architecture and terminology - of the moveit task constructor on a fairly high level. - -- :ref:`sec-howtoguides` help you to solve - specific problems and use cases you might encounter. - -- The :ref:`sec-api` provides - technical details of the python package. You may - look up definitions here and should already - have a basic understanding of the key concepts. +- :ref:`sec-tutorials` provide examples how to setup your task pipeline. + Start with :ref:`subsec-tut-firststeps` if you are new to MTC. +- :ref:`sec-concepts` discuss the architecture and terminology of MTC on a fairly high level. +- :ref:`sec-howtoguides` help solving specific problems and use cases. +- The :ref:`sec-api` provides quick access to available classes, functions, and their parameters. .. toctree:: :maxdepth: 2 :hidden: - tutorials + tutorials/index concepts - howtoguides - reference + howto + api diff --git a/core/doc/tut_cartesian.rst b/core/doc/tutorials/cartesian.rst similarity index 79% rename from core/doc/tut_cartesian.rst rename to core/doc/tutorials/cartesian.rst index 3cbdf409..222c3015 100644 --- a/core/doc/tut_cartesian.rst +++ b/core/doc/tutorials/cartesian.rst @@ -6,12 +6,12 @@ Cartesian The following example demonstrates how to compute a simple point to point motion plan using the moveit task constructor. You can take a look at the full source code here: -:download:`Source <./../../demo/scripts/cartesian.py>` +:download:`Source <../../../demo/scripts/cartesian.py>` First, lets make sure we specify the planning group and the end effector that we want to use. -.. literalinclude:: ./../../demo/scripts/cartesian.py +.. literalinclude:: ../../../demo/scripts/cartesian.py :language: python :lines: 14-15 @@ -19,7 +19,7 @@ The moveit task constructor provides different planners. We will use the ``CartesianPath`` and ``JointInterpolation`` planners for this example. -.. literalinclude:: ./../../demo/scripts/cartesian.py +.. literalinclude:: ../../../demo/scripts/cartesian.py :language: python :lines: 17-19 @@ -27,7 +27,7 @@ Lets start by initializing a task and adding the current planning scene state and robot state to it. This will be the starting state for our motion plan. -.. literalinclude:: ./../../demo/scripts/cartesian.py +.. literalinclude:: ../../../demo/scripts/cartesian.py :language: python :lines: 21-24 @@ -37,27 +37,27 @@ frame relative to which you want to carry out the motion. the relative direction can be specified by a ``Vector3Stamped`` geometry message. -.. literalinclude:: ./../../demo/scripts/cartesian.py +.. literalinclude:: ../../../demo/scripts/cartesian.py :language: python :lines: 26-31 Similarly we can move along a different axis. -.. literalinclude:: ./../../demo/scripts/cartesian.py +.. literalinclude:: ../../../demo/scripts/cartesian.py :language: python :lines: 33-37 The ``MoveRelative`` stage also offers an interface to ``Twist`` messages, allowing to specify rotations. -.. literalinclude:: ./../../demo/scripts/cartesian.py +.. literalinclude:: ../../../demo/scripts/cartesian.py :language: python :lines: 39-43 Lastly, we can compute linear movements in cartiesian space by providing offsets in joint space. -.. literalinclude:: ./../../demo/scripts/cartesian.py +.. literalinclude:: ../../../demo/scripts/cartesian.py :language: python :lines: 45-49 @@ -67,7 +67,7 @@ we use simple joint interpolation to move the robot to a named pose. the named pose is defined in the urdf of the robot configuration. -.. literalinclude:: ./../../demo/scripts/cartesian.py +.. literalinclude:: ../../../demo/scripts/cartesian.py :language: python :lines: 51-55 diff --git a/core/doc/tut_first-steps.rst b/core/doc/tutorials/first-steps.rst similarity index 100% rename from core/doc/tut_first-steps.rst rename to core/doc/tutorials/first-steps.rst diff --git a/core/doc/tutorials.rst b/core/doc/tutorials/index.rst similarity index 60% rename from core/doc/tutorials.rst rename to core/doc/tutorials/index.rst index 107d00c4..d62f5c24 100644 --- a/core/doc/tutorials.rst +++ b/core/doc/tutorials/index.rst @@ -9,7 +9,7 @@ of the moveit task constructor. .. toctree:: :caption: Tutorials - First Steps - Cartesian - Properties - Pick and Place + first-steps + cartesian + properties + pick-and-place diff --git a/core/doc/tut_pick-and-place.rst b/core/doc/tutorials/pick-and-place.rst similarity index 81% rename from core/doc/tut_pick-and-place.rst rename to core/doc/tutorials/pick-and-place.rst index c8d26dd9..6e4b1589 100644 --- a/core/doc/tut_pick-and-place.rst +++ b/core/doc/tutorials/pick-and-place.rst @@ -9,7 +9,7 @@ task constructor to plan and carry out pick and place movements. First, lets specify the planning group and the end effector that you want to use. -.. literalinclude:: ./../../demo/scripts/pickplace.py +.. literalinclude:: ../../../demo/scripts/pickplace.py :language: python :lines: 12-14 @@ -17,13 +17,13 @@ Next, we add the object that we want to displace to the planning scene. To this end, make sure that the planning scene not already contains such object. -.. literalinclude:: ./../../demo/scripts/pickplace.py +.. literalinclude:: ../../../demo/scripts/pickplace.py :language: python :lines: 16-33 At this point, we are ready to create the task hierarchy. -.. literalinclude:: ./../../demo/scripts/pickplace.py +.. literalinclude:: ../../../demo/scripts/pickplace.py :language: python :lines: 39-40 @@ -40,7 +40,7 @@ to sampling-based geometric motion planners. Lets connect the current robot state with the solutions of the following stages. -.. literalinclude:: ./../../demo/scripts/pickplace.py +.. literalinclude:: ../../../demo/scripts/pickplace.py :language: python :lines: 42-49 @@ -51,7 +51,7 @@ which essentially spawns poses with a given ``angle_delta`` in circular fashion around a center point. -.. literalinclude:: ./../../demo/scripts/pickplace.py +.. literalinclude:: ../../../demo/scripts/pickplace.py :language: python :lines: 51-56 @@ -62,7 +62,7 @@ The ``simpleGrasp`` stage combines ik calculation with motion plan generation for opening and closing the end effector, as well as attaching the object to the robot an disabling collision. -.. literalinclude:: ./../../demo/scripts/pickplace.py +.. literalinclude:: ../../../demo/scripts/pickplace.py :language: python :lines: 58-64 @@ -70,7 +70,7 @@ Lastly, we can insert all the previous steps into the ``Pick`` container stage. At this point we might also specify approach and lift twists for the robot relative to the object we want to grasp. -.. literalinclude:: ./../../demo/scripts/pickplace.py +.. literalinclude:: ../../../demo/scripts/pickplace.py :language: python :lines: 66-81 @@ -78,42 +78,42 @@ Since all the previous stages were chained together via their constructor arguments, we only need to add the top level ``Pick`` stage to the task hierarchy. -.. literalinclude:: ./../../demo/scripts/pickplace.py +.. literalinclude:: ../../../demo/scripts/pickplace.py :language: python :lines: 83-84 Thats everything we need for picking an object! Lets find a motion plan to place the object -.. literalinclude:: ./../../demo/scripts/pickplace.py +.. literalinclude:: ../../../demo/scripts/pickplace.py :language: python :lines: 86-87 Similar to the picking procedure, we define the place task. First, start with sampling place poses. -.. literalinclude:: ./../../demo/scripts/pickplace.py +.. literalinclude:: ../../../demo/scripts/pickplace.py :language: python :lines: 89-97 Next, wrap the inverse kinematics computation and gripper movements. -.. literalinclude:: ./../../demo/scripts/pickplace.py +.. literalinclude:: ../../../demo/scripts/pickplace.py :language: python :lines: 99-100 Lastly, add place and retract motions and add the ``Place`` stage to the task hierarchy. -.. literalinclude:: ./../../demo/scripts/pickplace.py +.. literalinclude:: ../../../demo/scripts/pickplace.py :language: python :lines: 102-121 Finally, compute solutions for the task hierarchy and delete the planner instances. -.. literalinclude:: ./../../demo/scripts/pickplace.py +.. literalinclude:: ../../../demo/scripts/pickplace.py :language: python :lines: 120-128 diff --git a/core/doc/tut_properties.rst b/core/doc/tutorials/properties.rst similarity index 79% rename from core/doc/tut_properties.rst rename to core/doc/tutorials/properties.rst index 15a695c4..6e825cd4 100644 --- a/core/doc/tut_properties.rst +++ b/core/doc/tutorials/properties.rst @@ -13,7 +13,7 @@ Basic Operations with Properties Lets define a property and assign a description, as well as a value to it. -.. literalinclude:: ./../../demo/scripts/properties.py +.. literalinclude:: ../../../demo/scripts/properties.py :language: python :lines: 18-25 @@ -21,13 +21,13 @@ Notice that a property always has two values: the current value and the default value. Before we use the property, we might want to check if the current value defined. -.. literalinclude:: ./../../demo/scripts/properties.py +.. literalinclude:: ../../../demo/scripts/properties.py :language: python :lines: 27-28 Now we are ready to safely retrieve the values of the proprty! -.. literalinclude:: ./../../demo/scripts/properties.py +.. literalinclude:: ../../../demo/scripts/properties.py :language: python :lines: 30-37 @@ -42,39 +42,39 @@ Lets first create a PropertyMap in isolation and initialize some properties using a dict. As you can see, properties can be of arbitrary type. -.. literalinclude:: ./../../demo/scripts/properties.py +.. literalinclude:: ../../../demo/scripts/properties.py :language: python :lines: 39-47 Properties can also be initialized using a more pythonic way. -.. literalinclude:: ./../../demo/scripts/properties.py +.. literalinclude:: ../../../demo/scripts/properties.py :language: python :lines: 49-50 There are two ways to retrieve properties back from the property map. We might only be interested in in the value of the property: -.. literalinclude:: ./../../demo/scripts/properties.py +.. literalinclude:: ../../../demo/scripts/properties.py :language: python :lines: 52-53 Or we can obtain a refernece to the whole property object. -.. literalinclude:: ./../../demo/scripts/properties.py +.. literalinclude:: ../../../demo/scripts/properties.py :language: python :lines: 55-56 The PropertyMap class additionally provides an iterator that can be used in loops. -.. literalinclude:: ./../../demo/scripts/properties.py +.. literalinclude:: ../../../demo/scripts/properties.py :language: python :lines: 58-62 Remember that wer initialized our PropertyMap by using a dict. In fact, you can also use an existing PropertMap to copy over some properties. -.. literalinclude:: ./../../demo/scripts/properties.py +.. literalinclude:: ../../../demo/scripts/properties.py :language: python :lines: 64-67 @@ -83,7 +83,7 @@ Accessing Properties of a Stage You can obtain a reference to the the PropertyMap of a stage like so -.. literalinclude:: ./../../demo/scripts/properties.py +.. literalinclude:: ../../../demo/scripts/properties.py :language: python :lines: 15-16, 74-75 @@ -92,7 +92,7 @@ Stages communicate to each other via their interfaces. If you want to forward properties through these interfaces, you can use the reference of a stages' property object. -.. literalinclude:: ./../../demo/scripts/compute_ik.py +.. literalinclude:: ../../../demo/scripts/compute_ik.py :language: python :lines: 27-28, 35-36, 40-42