The Rust API Guidelines suggest to use lines starting with # in examples to include example in a main method, so to able to use ?, etc, as in here.
We do this routinely in README.md files included by lib.rs, but we just noticed that while this works perfectly when calling cargo doc locally, in documentation on crates.io the #-lines are visible.
Has anybody experienced this problem? Is there a workaround?
That refers to documentation processed by rustdoc. It will remove those lines. The readme ist just rendered as markdown. Your options are:
It's not that easy. The whole point is to have the same README for Github (and there I understand the #'s will be there), for the generated documentation (and there the #'s are stripped and ingested correctly) and for crates.io. In the last case I thought that somehow the README would have been processed similarly to docs.rs (where the #'s are stripped and ingested correctly).
It's a bit of a pain not to be able to have a README that fully works everywhere.
Rustdoc never cares about README.md, so don't put # there. It just doesn't make sense.
I understand you're not familiar with doc inclusion syntax.
This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.