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

Doxygen output references file from other package #39

Closed mikepurvis closed 11 years ago

mikepurvis commented 11 years ago

The link to "example.cpp" at the bottom of this page.

Present: http://docs.ros.org/groovy/api/rosconsole/html/example_8cpp.html

Expected: http://docs.ros.org/groovy/api/diagnostic_updater/html/example_8cpp.html

Possibly related to #34.

jack-oquin commented 11 years ago

I opened a related issue with the Jenkins doc job.

Does the link get resolved correctly when running rosdoc_lite locally on the package source?

dirk-thomas commented 11 years ago

The problem is that the current doc job generates the documentation as well as the tag file in one run. Therefore doxygen uses the existing reference to example.cpp form the provided tag files (which is not desired).

In order to fix this the doc job should first generate the tag file for a package and in a second step generate the documentation for it (appending its own tag file at the end).

The list of tag files should also be generated in topological order which it currently isn't as far as I saw.

mikepurvis commented 11 years ago

Is the conflict arising because docs for a particular package must be built in a workspace containing all of its dependencies? Or do the docs get built in a single mammoth workspace containing everything?

dirk-thomas commented 11 years ago

Due to the number of the ROS packages we don't document packages in a big workspace. Instead each package is documented separately and uses doxygen tag files to allow cross referencing.

I think the conflict happens because doxygen does not prefer local references over ones coming from tag files. Therefore the package itself should use it's own tag file (after regenerating it before).

dirk-thomas commented 11 years ago

Doxygen can't fix this. The referenced name (example.cpp) is just not unique. In that case doxygen prefers the known reference from the tagfiles instead of searching the current project for a file with that name.

Instead the mainpage.dox of _diagnosticupdater must reference the file with a relative path. Then doxygen will prefer the local file instead of using the known reference from the tagfiles. I filled a ticket for that: ros/diagnostics#14