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!

[rkent]

Sorry for the long delay. I got around to testing this today. Here's some some notes for the future.

I implemented the changes to full_package above and built. The readme that shows on the main page (which is included from a generated file __readme_include.rst) properly shows the image, and properly links to other documentation. However, the link that appears under "Standard Documents/README) (/full_package/standard_docs/README.html) does not show the image nor the relative link properly.

This is because the standard documents have been rewritten to a separate folder, standard_docs and the relative links to doc/ don't work there.

Copying the standard docs to their own folder is useful, because then a simple glob in standards.rst can list the standard documents:

.. toctree::
   :maxdepth: 1
   :glob:

   standard_docs/*

In order to make relative documents work, I would have to copy standard documents to the root of wrapped_sphinx_directory, then manually generate the links in standards.rst rather than relying on a glob.

[rkent]

Apparently I already did what I suggested above in this unlanded commit I've been a little reluctant to move forward with some of these types of changes because I did not have a good example of an existing repo that would take advantage of this. This issue then helps with the motivation for that commit (and related commits).

The resulting display of readme has some issues though, namely that the image is not properly taking up space, so the following text is displayed on top of the image. I suspect that is because I am converting markdown to rst, and there is an issue in upstream dependencies. Anyway I'll face that when I try to land it.

[moschmdt]

Thank you for taking a look at the issue!

In the meantime I added the package to the ROS index, see rolling version. Apparently, the build farm does something different I assume, because the image is displayed there?

[rkent]

If I viewed this correctly, it is showing on the home page where it is included with the index.rst, but not in the direct display of the README file from http://docs.ros.org/en/rolling/p/soar_ros/standard_docs/README.html That is the same behavior I described.

[tfoote]

Is this resolved with #171 ?

[rkent]

Is this resolved with #171 ?

The specific issue mentioned here, that the image was not appearing, is now resolved.

His readme has a link:

.. figure:: doc/Images/soar_ros_slogan_default.svg
   :alt: logo

which previously showed on the home page, but not in the link. See #158 (comment)) This now works in both.

There are other links in that readme though that do not work, like:

Examples
--------

The following examples are an extract of the test cases in
`test/test_soar_ros.cpp <./test/test_soar_ros.cpp>`__.

Really there are two levels of issues:

• we are not copying the entire repo over to the wrapped directory, so some files are missing.
• people typically use the markdown from github as their test case, but many non-standard links that work there don't work in standard markdown.

That being said, I think we should close this issue and continue any further discussion of link failures elsewhere.