[ros-users] problems with generating documentation for ROS packages

[Ken Conley]

On Mon, May 30, 2011 at 12:28 AM, Rosen Diankov <rosen.diankov at gmail.com> wrote:
> We recently added a rosdoc.yaml file to the openrave_robot_control
> package that looks something like:
>
>  - builder: rosmake
>  - builder: sphinx
>   name: roslaunch scripts
>
> But since we added the documentation file, the wiki has stopped
> getting updated. we're not sure how to debug the problem since we
> don't know what frequency ros.org is updated and what the errors
> are... can anyone help with this?

The job that builds the documentation is here, the output is a bit
large to grok through due to the size of the indexer:

http://build.willowgarage.com/job/rosdoc/?

It runs multiple times per day.

The first thing you could verify for me is that it works with a
vanilla rosdoc command, i.e. no additional system installs.  I don't
understand well enough what hooks you are leveraging to get sphinx to
produce this output.   The build job does not do any rosdep
installation, and it currently configures against trunk of most
packages/stacks.

In Fuerte turtle, we're hoping to change the indexer to be
distribution-specific now that we have enough external stacks releases
to work against.

> Also, we recently added auto documentation of launch files, which
> requires we put a <sphinxdoc> tag in the launch files themselves.

Is there a reason why you use a tag and not formatted comment markup?
It seems the latter is the more commonly used approach and would cause
less parse issues.

>
> http://www.ros.org/doc/api/jsk_tools/html/
>
> We have documented a problem we're having with this here, but there
> are still no responses after a week. I'm not sure if answers.ros.org
> was the wrong place to post it or not..
>
> http://answers.ros.org/question/988/adding-extra-tags-in-xml-launch-files

I was away on vacation when you posted. I have added an answer.

 - Ken

> thanks,
> rosen,
> _______________________________________________
> ros-users mailing list
> ros-users at code.ros.org
> https://code.ros.org/mailman/listinfo/ros-users
>