Adding more documentation for MTC

[Abishalini]

I have been working with MTC for some time and I had to learn MTC by digging through source code. I would like to help add more docs on how MTC works and how to use MTC.

Here are some of the things I'd like to focus on

• [ ] Enable auto-generated API docs on ROS Index. The API docs for MTC is basically empty for Noetic and non-existent for ROS 2.
• [ ] How to render the existing MTC docs on the web (if at all possible)
• [ ] Add more documentation on each stage provided by MTC - properties, etc.
• [ ] Add more documentation on how to debug MTC tasks and monitor solutions
• [ ] (Low Priority) Document the structure of MTC. I attempted to create a UML diagram

I started adding docs on MTC to the MoveIt2 tutorials concepts page - https://github.com/ros-planning/moveit2_tutorials/pull/809 But it might be better to contribute here so that the documentation lives close to the source code.

I would like some feedback on this effort and some reviews on the docs I have already started working on.

[rhaschke]

Thanks for this initiative! Your help on improving the docs and your (external) view on MTC are very welcome. As pointed out in the opened PR, I would prefer augmenting the docs here, which reside in folder core/doc. They are automatically deployed to https://ros-planning.github.io/moveit_task_constructor.

[Abishalini]

@rhaschke I'm trying to figure out how to build the docs locally so I can verify my changes. Do you have instructions on how to do that?

[rhaschke]

You can find the build instructions in the ci.yaml workflow (of the master branch): https://github.com/ros-planning/moveit_task_constructor/blob/a90557279ca306fc30d39ec463af401022314b17/.github/workflows/ci.yaml#L143-L144

[eholum]

Thanks @rhaschke. Do you have any ideas on versioning the docs for the ros2 and master branches? We're not sure how simple it will be to support multiple branches on the on the docs site. But there might be some work in tweaking CI/the pages config in order to support that. Is that something you happen to have done before?

[rhaschke]

I haven't considered versioning the docs so far. But moveit2_tutorials is already using different versions, isn't it?

[eholum]

I haven't considered versioning the docs so far. But moveit2_tutorials is already using different versions, isn't it?

Yep! The moveit2_tutorials use sphinx multi-version, combined with some matrix magic in CI to get the versioning working there. I'm not sure how much work it would be to replicate here, but something similar would probably work. I am not familiar with how much effort it is to setup and maintain, though.