rust-lang
README example rendering doesn't hide lines
Current Behavior
I just looked at the crates.io page for my crate, service-skeleton, and noticed that the lines that I thought I'd hidden (using the standard rustdoc mechanism) are showing up in the rendering of the README (such as the line in the first example, under the "Usage" heading, that reads // Yes, this is cheating and the line before/after).
Expected Behavior
The lines that I'm trying to hide wouldn't show up in the README rendering on crates.io.
Steps To Reproduce
- Go to https://crates.io/crates/service-skeleton
- Scroll down to "Usage"
- Look at the first example
- Observe that there are lines starting with
#visible.
Environment
No response
Anything else?
It's possible I've misunderstood how doctests work, in which case, my apologies, and I'd appreciate a pointer towards what I should be doing instead.
they're also showing up on https://github.com/mpalmer/service-skeleton#usage, which is what we're roughly trying to match. these lines are only hidden on docs output.
Yeah, I expect them to show up on GitHub, because it's not likely to understand rustdoc conventions. I figured crates.io, being a Rust-specific site, would be more likely to follow how rustdoc does things, but if not, I guess I'll just have to pull the examples out of the readme, or learn to live with it.
I think I missed this issue while travelling in March. (Sorry, @Turbo87!)
I'm kind of -0 on this, honestly.
docs.rs also doesn't treat README files with rustdoc/doctest conventions: note that the # prefixed lines are also visible at https://docs.rs/crate/service-skeleton/0.4.1. I'm also worried that we end up implementing even more of a Markdown dialect that doesn't match anything else: are there other rustdoc features that we'd then need to special case in our Markdown renderer?
Also, unless I'm missing something (probable), rustdoc and cargo test --doc don't generally try to test standalone Markdown files, right? So there's no need for them to be complete, runnable examples for testing purposes — if they are, then I wonder if it makes more sense for them to live in the package-level documentation (ie in src/lib.rs, so in this example at https://docs.rs/service-skeleton/0.4.1/service_skeleton/), instead of being in the README (which might be better served with copy/pastable snippets, regardless of whether they compile as full blown standalone doctests).
But, again, I'm -0, not -1. I guess I think of standalone Markdown files as being a little bit different to inline documentation, but it wouldn't be the first time I have weird ideas about things that most people don't. :laughing:
we discussed this issue in our team meeting last week and concluded that while we don't have a strong opinion we are leaning towards mimicking what GitHub does, instead of Rustdoc.
the best way forward for you would be to find an example snippet for the readme that does not need hidden lines. that will have the added benefit of also rendering the same on GitHub then.