search

ros-infrastructure / rosdoc2

Command-line tool for generating documentation for ROS 2 packages.
Apache License 2.0
40 stars 11 forks source link

Packages that define conf.py in standrd locations usually fail #120

Open rkent opened 7 months ago

rkent commented 7 months ago

I scanned rolling packages, and looked for packages with a conf.py in a standard location: doc/ or doc/source/. I found 18. Of these, 10 had serious failures (either no rosdoc2 result at all, or failure to show intended documentation:

conf.py failures:

  1. geodesy
  2. naoqi_driver
  3. cv_bridge
  4. mrpt_path_planning
  5. robot_localization
  6. ffmpeg_image_transport (readme_include fails)
  7. ffmpeg_image_transport_tools (just shows package name)
  8. quaternion_operation (just shows package name)
  9. event_camera_py (rst files not shown; failed READMR include)
  10. mrpt2

The reasons were varied, but some common reasons:

Of those who define conf.py, several would be better off with our newer rosdoc2 implementation rather than trying to roll their own. In others, the result would be better under our new documentation section rather than replacing all of the rosdoc2 output.

rkent commented 3 months ago

Just as a FYI, I've been working recently on trying to understand and overcome issues of rosdoc2 failures from a variety of sources, including this one. So this issue is rather stale, but eventually I'll propose PRs for these issues.