search

ros-infrastructure / rosdoc2

Command-line tool for generating documentation for ROS 2 packages.
Apache License 2.0
29 stars 9 forks source link

Directories reports an absolute directory rather than relative, and in worst case shows all parent directories #71

Closed rkent closed 2 months ago

rkent commented 3 months ago

When you run rosdoc2 on a C++ project, the Directories html shows the full path to the original directory, which is typically in some sort of staging location. It should show the relative directory.

For example, In https://docs.ros.org/en/rolling/p/rosbag2_cpp/generated/dir__tmp_ws_src.html we have:

Directory path: /tmp/ws/src

which is exposing the buildfarm directories used here. '/tmp/ws' is of no interest, it should just say 'src'.

Worse, if the doc build directory is specified, then the Directories list will go all the way back to the drive root. So if I run rosdoc2 in /home/kent/github/ros2/demos/demo_nodes_cpp with:

rosdoc2 build -p . -d /tmp/rkent/docs_output

Then the directories listing at http://localhost:8001/docs_output/fqdemo_nodes/generated/index.html#directories shows:

Directories
    [Directory home]
    [Directory kent]
    [Directory github]
    [Directory ros2]
    [Directory demos]
    [Directory demo_nodes_cpp]
    [Directory include]
    [Directory demo_nodes_cpp]

Instead, it should just show include and demo_nodes_cpp The fix to this is relatively straightforward: set STRIP_FROM_PATH in the Doxyfile. I'll give a PR with that change, but I would like to add a test for it so I'll wait for the my previous PR.

rkent commented 3 months ago

Fixed with test in my repo branch

tfoote commented 3 months ago

That's quite a obscure option that seems like it should be on by default.

Diff for easier reivew: https://github.com/ros-infrastructure/rosdoc2/compare/main...rkent:rosdoc2:Only-show-relative-directories-%2371

It looks ready to merge. Is there anything else you feel needs to be checked before opening a PR on this?

rkent commented 3 months ago

There could be a couple of concerns. One is cross-package links. I believe my most advanced branch has a test case for that, I'll check. Also exhale includes a lot of commentary on this option that I don't really understand. So I want to examine it some more. It's one of those issues that seem trivial, but could have unforeseen consequences if it messes with links.