Problems with table export

[stefan-k]

Firstly thank you for this great tool! :) I'm very happy to see that there is a replacement for cargo readme.

I'm experiencing a problem; however, I'm unsure if it falls into the category "verbatim copy of your markdown" of your non-goals. If it does, apologies and please just close this issue.

In particular I'm experiencing problems with the export of tables. Given a table like this:

//! | Header1  | Header2 |
//! |----------|---------|
//! | A        | B       |
//! | C        | D       |

the output looks like this:

| Header1  | Header2 | |–––––|———| | A        | B       | | C        | D       |

which won't render correctly because the line breaks are missing and because "wrong" dashes are used (– instead of -; strangely not for all columns).

[msrd0]

When I copy your input into a new crate and run cargo doc2readme, I get this output

| Header1 | Header2 |
| --- | --- |
| A | B |
| C | D |

which seems to be correct (removing invisible whitespace falls into the non-verbatim copy of your markdown category). Can you provide any additional details so I can reproduce the problem?

[stefan-k]

Thanks for your quick reply! I looked at it more closely and it seems that --expand-macros is causing this issue. It works without this option.

[msrd0]

Works for me with and without this option

[msrd0]

I don't think there's much I can do here. Your output makes me think that pulldown-cmark didn't recognize your input as a table, so without more details, I have to assume there are some problems with your input (maybe missing a newline in front of your table?).

[stefan-k]

Sorry to not reply earlier, but testing takes a couple of minutes.

I was using the version from crates.io. I just compiled the latest code on Github. It works when compiling from source, but now I seem to be having other issues with expanding macros.

Anyway, thanks.

[msrd0]

I was also testing with the latest release. If you provide further details I'm happy to reopen the issue.

[stefan-k]

Somehow related to expanding macros.

This produces broken tables:

//! blah blah
//!
#![doc = concat!("blahblah = \"", env!("CARGO_PKG_VERSION"), "\"")]
//!
//! | Header1  | Header2 |
//! |----------|---------|
//! | A        | B       |
//! | C        | D       |
//!
//! blah blah

This works:

//! blah blah
//!
//!
//! | Header1  | Header2 |
//! |----------|---------|
//! | A        | B       |
//! | C        | D       |
//!
//! blah blah

Using latest release:

cargo doc2readme --out README.md --expand-macros

[msrd0]

Oh I see, there's some problem with the indentation. Workaround: Put an extra space at the beginning of the line, like so

#![doc = concat!(" blahblah = \"", env!("CARGO_PKG_VERSION"), "\"")]

[msrd0]

It looks like rustdoc removes at most 1 leading space from doc comments if that leading space is present in all doc comments for an item. It never removes leading spaces from doc attributes.

The problem is that when parsing with syn, all doc comments are turned into doc attributes without any space removal (similar to how cargo expand works). This means that we either need a way to differentiate doc comments and doc attributes, which is unlikely to happen since syn is designed to be used in proc macros where the compiler already produced doc attributes from comments (syn doesn't even have // or /// or //! as tokens). Or we need to pre-process the input, counting leading spaces of doc comments and potentially trimming them before passing the input to syn. Also, one might need to investigate how multi-line doc comments (/*! ... */) are handled.

Either way it's going to be a breaking change, as fixing the bug will break its workaround.