rosindex landing page is garbled version of README.md. How to replace with rosdoc2 generated page?

[berndpfrommer]

The landing page of my ros package is a somewhat disfigured version of the README.md that is on github (note the numbered items 1), 2) etc at the bottom under the "About timestamps" heading are all gone and merged into one blob).

I had hoped that somehow I could get the page generated by rosdoc2 to show up instead of the translated README.md.

Note: this issue is a follow-up to issue #58

[rkent]

This issue should really be in rosindex.

rosdoc2 uses python and the myst md parser, while rosindex uses ruby, jekyll and the "red carpet" parser (though that might need to switch to kramdown since "red carpet" support is deprecated in jekyll. So your literal request, "make them the same" is not really feasible.

I think though that your issue is that the formatting in rosindex does not match what you want toward the end, with the numbered list in ## About Timestamps. Right?

Markdown is not a well-defined specification, so there is no "right" way to do things. But generally, numbered lists are created like:

1. An Item

NOT

1) An Item

Both seem to work here in Google markdown, but the period format is more normal IIUC. Also, you ran together your numbered paragraphs: 1) First 2) Second

Many markdown implementations will merge that into a single paragraph, as you can see in rosindex. I've seen different specs on how to prevent that, one says "add a blank line" another says "add two spaces at the end of the line".

I did a rosindex run where I replaced the parentheses with periods at the end of your README, like so:

## About timestamps

A message in a recorded rosbag has three sources of time information:

1. The recording timestamp. This is when the message was written into
the bag by the rosbag recorder. It is the least precise of all time
stamps and therefore usually not used.
2. The message time stamp in the header (header.stamp). This is the
time when the ROS driver host received the first event packet from the SDK
for that ROS message. Remember that a ROS message can contain multiple
SDK packets, but the header.stamp refers to the first SDK packet
received.
3. The sensor time encoded in the packets. This time stamp depends on
the encoding. 

You can see the result of that (temporarily) at http://test.caspia.com/p/event_camera_py/ The numbered list is now separated. You could also have accomplished the same thing by adding two spaces at the end of the numbered lines to force new lines.

Inconsistencies in markdown are a pain, and I wish rosindex was in python instead of ruby/jekyll. But that is where we are at, and that is not likely to change.

[berndpfrommer]

@rkent Thank you very much for the fast, detailed, and very helpful response! Sorry I was blissfully unaware of rosindex vs rosdoc2. I just assumed that rosindex would run rosdoc2, but apparently not so. Thank you clarifying that. I fixed the markdown in my README.md. Hopefully this will render better now on rosindex.