Code in documentation that's conditionally started with or ignore based on feature doesn't render correctly

[marcianx]

Current Behavior

I just published downcast-rs v2.0.0 and the documentation appears misformatted even though it appears fine on docs.rs. Compare:

• https://crates.io/crates/downcast_rs/2.0.0
• https://docs.rs/downcast-rs/2.0.0/downcast_rs/

This seems due to code within the documentation that is only conditionally run for testing based on whether a feature is enabled:

...
//! Since 2.0.0, the minimum supported Rust version is 1.56.
//!
#![cfg_attr(feature = "sync", doc = "```")]
#![cfg_attr(not(feature = "sync"), doc = "```ignore")]
//! # #[macro_use]
//! # extern crate downcast_rs;
...

Effectively, the code block is being started with ``` when the sync feature is enabled and with ```ignore when it's disabled.

Actual code here.

Also:

• Any workarounds?
• Any way to discover such issues before publishing?

Expected Behavior

crates.io should render the documentation as well as docs.rs does.

[marcianx]

A workaround is to replace conditional docs with conditional code within the test. E.g.

//! Since 2.0.0, the minimum supported Rust version is 1.56.
//!
//!```
//! # #[macro_use]
//! # extern crate downcast_rs;
//! # #![cfg(feature = "sync")]
//! // <Code to ignore when "sync" is enabled.>

Would still love to have a way to discovering such issues before publishing.

[Turbo87]

I'm not sure what exactly the issue here is. Our aim is to render the readme files roughly like they would be on GitHub and https://github.com/marcianx/downcast-rs/blob/v2.0.0/README.md looks somewhat similar to https://crates.io/crates/downcast_rs/2.0.0 to me 🤔

[Turbo87]

https://docs.rs/crate/downcast-rs/2.0.0 also looks similar FWIW

[marcianx]

Oh, that's interesting! What's the difference between these two

• https://docs.rs/downcast-rs/2.0.0/downcast_rs/
• https://docs.rs/crate/downcast-rs/2.0.0
  ? Is the latter a new version by any chance?

You're right that github is similar, and I should have glanced over at that rendering first!
I would still love to know -- is there any way for me to test this locally? I just tested with cargo doc --open, and when it looked good there, I thought it would work on crates.io and docs.rs.

[Turbo87]

One is the rendered Readme and the other is the main doc comment a rendered by rustdoc

[marcianx]

Oh! That's the important distinction! Thank you!
I suppose I should probably just have the README point to docs.rs instead of duplicating the documentation with cargo-readme.