Cras_docs_common: Give the Python docs some shine again!

peci1 · 2023-03-08T13:56:22.813Z

After today’s doc job rerender, I’m proud to show you the nicest (both visually and functionality-wise) documentation page I’ve ever made for ROS 1. Many people know about the sad state of Python docs in Noetic. So I’ve decided the way Python packages are documented needs some refresh.

The reusable ROS 1 package cras_docs_common allows you to create nice Sphinx Python documentation for any ROS package with very simple configuration. No more need to copy-and-paste the conf.py Sphinx config to every package you make. Now there’s a single one that rules them all Available for Melodic and Noetic.

Aside from the visual theme, the package adds a lot of convenience to documenting ROS code. Use :roswiki:`cras_py_common` to generate references to ROS wiki. Use :tf2_msgs:`TFMessage` to refer to the API docs of TFMessage.

Cross-references to base Python APIs and numpy are also resolved, as well as cross-references to ROS messages and services.

As an example of a page generated by this package, look for example at image_transport_codecs — image_transport_codecs 2.1.2 documentation :

Screenshot 2023-03-08 at 14-49-14 image_transport_codecs package — image_transport_codecs 2.1.2 documentation1853×1087 322 KB

Let me know if you have any feedback!

system · 2023-04-07T13:56:34.393Z

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.