Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages (we want Python as well). As in every other software tool, the best way to learn it is starting to use it in your everyday life. There are many examples and tutorials online.
It’s nice to adopt traditional software developing tools when we work with ROS and robotics software. I think that it worths to watch the next video presented in the ROS-Industrial Consortia. Enjoy!