Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
marcianx opened this issue Jan 7, 2025 · 1 comment

Comments

@marcianx
Copy link

marcianx commented Jan 7, 2025

Current Behavior

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

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
Copy link
Author

marcianx commented Jan 7, 2025

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant