search

ros2 / docs.ros2.org

http://docs.ros2.org
Creative Commons Attribution 4.0 International
0 stars 4 forks source link

Make message docs findable #50

Closed nnmm closed 1 year ago

nnmm commented 3 years ago

There are no relevant results when Googling "sensor_msgs foxy ros2", not even for "site:docs.ros2.org sensor_msgs". The docs actually do exist at http://docs.ros2.org/foxy/api/sensor_msgs/index-msg.html, along with all the other official message packages. Nothing links to these pages or they would be indexed by Google, and even their URL is hard to guess (you might try index.html but not index-msg.html). index.ros.org also links to http://docs.ros2.org/foxy/api/sensor_msgs/ which gives a 404 error. So no one knows they exist and is left to guess whether the ROS1 docs still apply – including me until I looked at this repo.

I propose generating a http://docs.ros2.org/<distro>/api/index.html which lists all the packages, and linking to that one from the main http://docs.ros2.org/<distro>/index.html page. Additionally, either the name of the package documentation should be changed to index.html or the links in index.ros.org be adjusted.

I can take a stab at the first item although I don't really know Sphinx and Doxygen well, I'll let you know how it goes.

nnmm commented 3 years ago

I ran into make: *** No rule to make target 'src/micro-ROS/ros_tracing/ros2_tracing/tracetools/Doxyfile', needed by 'src/micro-ROS/ros_tracing/ros2_tracing/tracetools/doc_output/html'. Stop..

The micro-ROS directory doesn't exist in /tmp/<subdir>/src, but ros_tracing/ros2_tracing/tracetools does. Any ideas how to fix this?

clalancette commented 3 years ago

I'd suggest holding off on this. We are currently in the process of moving all of the documentation to a common place; see http://design.ros2.org/articles/per_package_documentation.html for what we are currently working towards.

christophebedard commented 3 years ago

Any ideas how to fix this?

Change instances of micro-ROS/ros_tracing to ros-tracing in https://github.com/ros2/docs.ros2.org/blob/6bdaae93ec2542daa8e573644e2aee59842201e7/Makefile. It was moved in the ros2.repos files (all the versions) but the config here wasn't updated.

nnmm commented 3 years ago

Thanks for your quick replies. I saw per-package documentation being mentioned elsewhere, but had estimated the effort of generating such a listing in the current bash script setup to be relatively small (if it's not required to be pretty), and wasn't sure when this will arrive. Is there a repository or timeline for it somewhere?

clalancette commented 1 year ago

I'm going to close this out, as we no longer use this repository and I am going to archive it.