search

ros-infrastructure / rosdoc_lite

A light-weight version of rosdoc that does not rely on ROS infrastructure for crawling packages.
10 stars 31 forks source link

Comments in msg and srv file are not preserved in the generated documentation #29

Closed tompe17 closed 10 years ago

tompe17 commented 11 years ago

Comments in msg and srv file are not preserved in the generated documentation. With rosdoc they were kept.

jack-oquin commented 11 years ago

For a specific example, see the current wiki page for NavSatFix, and compare the many useful comments omitted from the message source.

eitanme commented 11 years ago

Good point. I've put support for raw messages back in. This should fix up all the documentation the next time all the doc jobs run. To give an example, however, I manually triggered groovy for sensor messages.

Relevant commits: groovy: https://github.com/ros-infrastructure/rosdoc_lite/commit/1ee1fe2993ad4eb504867dd5325adfce63d2cfa4 fuerte: https://github.com/ros-infrastructure/rosdoc_lite/commit/88e97896bbfa653b9ae8c4c4205a8e903442b168

Example: http://www.ros.org/doc/groovy/api/sensor_msgs/html/msg/NavSatFix.html

jack-oquin commented 11 years ago

Looks great. That fixed it. Thanks, Eitan!

tompe17 commented 11 years ago

Is this fix in the latest Ubuntu packages? Or how do I enable it?

jack-oquin commented 11 years ago

It is periodically collecting documentation for the wiki for all repositories listed with the documentation indexer.

To use it, follow the instructions for adding your repository to the index.

tompe17 commented 11 years ago

My use case is private documentation. So I am generating the documentaion like:

add_custom_target (lrs_cons_doc
  rosdoc_lite -o ${CATKIN_DEVEL_PREFIX}/doc/lrs_cons ${CATKIN_DEVEL_PREFIX}/../src/lrs_cons
)

But I do not seem to get the raw message included in the generated file. With rosdoc things worked...

tompe17 commented 10 years ago

The commit above that add this functionality seems not to be in the distributed rosdoc_lite package.

jack-oquin commented 10 years ago

@tompe17: I believe you are correct.

Since rosdoc_lite was not actively maintained, I recently volunteered to maintain it. I plan to make a new release in the next few days. I will close this issue again, when that has been accomplished.

The reason the build farm picked up the fix was because it checks out and builds the source directly from github. You can do the same, if you need Eitan's fix before it becomes available via the release pipeline.

jack-oquin commented 10 years ago

Fix released to Groovy and Hydro.

tompe17 commented 10 years ago

So when will it appear in the debs? Still not there for me.

jack-oquin commented 10 years ago

They have been in the ros-shadow-fixed repository for several days now. Tully promotes batches of package updates from there to the ros repository when it makes sense for the ROS community as a whole. I have no visbility into the timing of that, so I normally close issues when the fix is in the release pipeline.

Please try out the shadow fixed Debian. That just requires temporarily editing your /etc/apt/sources.list.d/ros-latest.list file. Unless you do a lot of work with recently released packages, I would recommend changing it back after you install ros-groovy-rosdoc-lite.

If it does not fix your problem, we'll reopen this issue.

jack-oquin commented 10 years ago

I just installed the shadow-fixed Debian and ran it on a message package. It works for me.