enable doc_auto_cfg to show feature-req-hint in docs.rs

[kingwingfly]

Pull Request Template

Checklist

• Confirmed that run-checks all script has been executed.
• Made sure the book is up to date with changes in this PR.

Related Issues/PRs

None

Changes

According to this, cargo doc has an cool feature doc_auto_cfg, which helps show the features-required hints like tokio.

# in lib.rs
#![cfg_attr(docsrs, feature(doc_auto_cfg))]

# in Cargo.toml
[package.metadata.docs.rs]
features = ["doc"]
rustdoc-args = ["--cfg", "docsrs"]

Apart from that, I also add documentation keys in [package].

Testing

RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --features doc --no-deps -p burn --open

I just checked that it works and show things like:

But I don't know how to automize this with xtask, and it needs nightly Rust as the version used by docs.rs.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 85.41%. Comparing base (aa79e36) to head (1999267).
Report is 25 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2271      +/-   ##
==========================================
- Coverage   85.79%   85.41%   -0.39%     
==========================================
  Files         754      767      +13     
  Lines       95189    97960    +2771     
==========================================
+ Hits        81671    83669    +1998     
- Misses      13518    14291     +773     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[nathanielsimard]

Somehow it doesn't work for everything:

I would have expected the backend modules to show which feature flag is necessary, do you have an idea why it doesn't appear to work for those?

[kingwingfly]

I'll try to fix this.

I guess it is because features like ndarray tch are not enabled with doc.

[kingwingfly]

Oh, it seems not so simple. However, it works well for package burn-core and package burn-train:

But it fails when coming to package burn.

It's so buggy, and I may spend more time in finding the fixing method.

[kingwingfly]

@nathanielsimard

I found a way to fix this, and now it works for burn package. However, it is just to re-export all things in burn_core and burn_train instead of easily pub use burn_core::*, now it looks quite tedious.

I have compared the new doc page and the old, and I think nothing lost. I hope I didn't forget exporting something.

[laggui]

@nathanielsimard

I found a way to fix this, and now it works for burn package. However, it is just to re-export all things in burn_core and burn_train instead of easily pub use burn_core::*, now it looks quite tedious.

I have compared the new doc page and the old, and I think nothing lost. I hope I didn't forget exporting something.

That seems a little error prone 😅 would be nice if there was a way to do this properly without re-exporting

[kingwingfly]

That seems a little error prone 😅 would be nice if there was a way to do this properly without re-exporting

I hope so. I found current less graceful solution by a minimal example. I'll try asking for help from the feature developper and the community.

[kingwingfly]

I just found this is allowed:

pub use crate_a::*; // instead of `pub use crate_a::{B, C, D, ...}

#[cfg(feature = "a")]
pub use crate_a::A;

Now it will be less possible to make a mistake.

By the way, as the features are given in the Cargo.toml, it is reasonable to use it in the package somewhere explicitly maybe...

The features are written in Cargo.toml only for generating feature page, and user can still enable them with --features tch,train even without them in Cargo.toml. So, using it in lib.rs can at least make them more meaningful.

And I found there are also many problems about features in this repo. For example, my editor told me tch and train features are enabled even they are not included in default feature. And they are actually enabled by example/text-generation. This can be prevented by required-features, and it's also tedious to fix ( here's an example: 1. set required features and 2. set --features for each example )... I'll make another issue as I become available.

[nathanielsimard]

@kingwingfly When building an example from the root workspace directory, all dependencies listed in the workspace are built, not one the ones specified in the example. I though this was a cargo workspace thing, is there a way to remove that behavior?

[kingwingfly]

@nathanielsimard

#2289

Using required-feature can solve this problem. But it then needs to modify test and example shell scripts to enable features needed.

[nathanielsimard]

I don't like the fact we need to know when adding a new metrics, that it should be manually re-exported in the burn root crate. Only for the feature flag to show on the docs :/