Relative image paths and links on root README not parsed?

[moschmdt]

A project I am working on, soar_ros, uses its projects README as the main README file in the static HTML documentation generated via rosdoc2 in a CI job. The resulting landing page has the original image links, and file links to related documentation not parsed. For instance, the path when analyzing the HTML image is still doc/Images/soar_ros_slogan.svg and the image is not even located in the _images directory of the output branch gh-pages.

Since this applies to relative links to other files and relative image links, I suspect that paths are not adjusted accordingly/parsed?

Thanks for all your work on the tool and the progress made recently!

[rkent]

I'm having a hard time locating where the links are in your docs that are causing problems for you. Could you be very specific for me please?

[moschmdt]

Reproducible minimum working example

I extended the full package test in this commit in my fork by an image and a relative link.

This is an example image that should be displayed on github.com and the
generated documentation website.
![ROS 2 logo](doc/Images/ros_2_logo.png)

The link to [somethingElse.markdown](doc/somethingElse.markdown) should also
work in both environments.

Steps to reproduce issue:

1. Build full package test via rosdoc2 build ... from fork
2. Open corresponding index.html
3. Only alt text of the image is displayed, and the link to the other Markdown file is not working.

Raw markdown (expected similar results in rendered version)

Rendered version

Version of rosdoc

rosdoc2==0.2.1

[rkent]

Thanks for the details.

I don't have time for a few days to look specifically at your situation, but let me respond from memory about my general investigations in this area. I am aware of the general problem, and have tried to take steps to mitigate it, though not entirely successfully at this point.

rosdoc2 copies portions of the original package source to a temporary location where the rendering software is run. This is because we add a lot of automatic documentation, and if we did not do that, the source files of your repo would be spewed with our stuff. Some of those copies did not preserve the original directory structure, but in the last few months changes have been done to rosdoc2 to try to preserve the original directory structure as much as possible, in the hopes that relative links would work.

But what I recall is that, even after doing that, there was no way to make relative links that worked in both github and rosdoc2. I don't remember the exact issue, but I do recall thinking it might be possible to write a sphinx extension that would solve the problem.

Sorry I can't be more specific, maybe next week I can give it a deeper look and see if I cam make any recommendations for your specific situation.

[moschmdt]

Thank you for your quick responses and clarification!