Python packages not documented correctly

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

Python packages not documented correctly #38

Closed dirk-thomas closed 10 years ago

dirk-thomas commented 10 years ago

There are currently multiple issues:

[x] having no documentation at all (e.g. http://docs.ros.org/hydro/api/rospy/html/index.html)
[x] the documentation only contains an empty package (e.g. http://docs.ros.org/hydro/api/dynamic_reconfigure/html/)
[x] source code for code implemented in the package init.py file is not available (e.g. http://docs.ros.org/groovy/api/rostest/html/)
[x] for python packages the doxygen documentation lacks most of the content (e.g. http://docs.ros.org/hydro/api/uuid_msgs/html/)

dirk-thomas commented 10 years ago

Yes, the doc job did only run cmake and make for the message targets and then documented the results from the devel space which is obviously incomplete as it does not contain the Python sources.

dirk-thomas commented 10 years ago

I ran the doc jobs for _roscomm and _dynamicreconfigure for Hydro with --force and both API documentations seems to be complete now.

jack-oquin commented 10 years ago

Thanks for fixing. I've seen some other Python packages whose docs did not get expanded correctly.

I'll have to wait for the build farm cycle to see if this fixes them, too.

Or, is there some way for me to trigger doc builds?

dirk-thomas commented 10 years ago

No, their is no way to trigger that easily since the doc job needs to be triggered with the --force option to regenerate the docs even when the upstream has not changed.

If you have a handful of repos in mind please just post their names here and I can retrigger them manually to iterate faster than having to wait three days.

jack-oquin commented 10 years ago

These two worked on Groovy but not Hydro:

https://github.com/ros-geographic-info/unique_identifier https://github.com/ros-geographic-info/geographic_info

dirk-thomas commented 10 years ago

I reran both jobs for Hydro with --force (http://jenkins.ros.org/view/Hdoc/job/doc-hydro-unique_identifier/91/ http://jenkins.ros.org/view/Hdoc/job/doc-hydro-geographic_info/91/).

For unique id and geodesy the Groovy and Hydro sphinx pages look similar and complete to me. Can you confirm that?

But for _uuidmsgs and _geographicmsgs the doxygen docs for Hydro look incomplete. Is that what you refer to?

jack-oquin commented 10 years ago

Looks OK. Thanks.

dirk-thomas commented 10 years ago

But _uuidmsgs and _geographicmsgs look incomplete, no?

jack-oquin commented 10 years ago

They look OK to me. They are just message packages and the messages are documented.

What is missing?

dirk-thomas commented 10 years ago

I compared http://docs.ros.org/groovy/api/uuid_msgs/html/annotated.html and http://docs.ros.org/hydro/api/uuid_msgs/html/ and thought that Hydro lacks information. But looking closer Groovy just contains docs of dependent code. So I guess you are right - that should be sufficient. Thanks for checking.