Improve docs.rs builds

[novacrazy]

While working on generic-array 1.0, I noticed docs.rs does not contain the const-generics portions of typenum, so the links were broken. Enabling support for that with automatic "Available on crate feature const-generics only." text would have been easy, except for the force_unix_path_separator feature interfering with it.

After looking through the commit history, your original commit and message 694130d implied enabling the feature made it more compatible. If I'm wrong, please correct me, but I don't see any reason why this should not be the default behavior. Making force_unix_path_separator the default behavior has no visible downsides and allows doc_auto_cfg to function correctly, more or less.

I added a couple extra hints to rustdoc for i128 implementations as well. Unfortunately, these rustdoc hints don't work for the scale-info derives, so they are still excluded from docs.rs.

As a bonus, I added a Rust Playground metadata section to enable i128 and const-generics support there.

[novacrazy]

@paholg I'm looking to get generic-array 1.0 published as soon as possible, but with typenum not documenting the const-generics feature, docs.rs links will be broken. Could this PR be looked at? Or delegate it to another maintainer.

[paholg]

Sorry for the delay. Just want to make sure we're not breaking anything for anyone with removal of force_unix_path_separator and I'll be happy to merge/publish.

[MingweiSamuel]

This just breaks the build on windows?

#107
#108
#125

#147

[paholg]

This just breaks the build on windows?

Can you be more specific? Typenum's CI runs builds on Windows, so there are at least some cases where it doesn't.

[MingweiSamuel]

Yes, seems it only occurs in a situation where "\\?\" gets prepended to OUT_DIR env var. Not sure why that is getting appended, but testing shows that it is causing the error:

mod gen1 {
    include!(r"D:\Projects\typenum_test/include.rs");
}

mod gen2 {
    include!(r"\\?\D:\Projects\typenum_test\include.rs");
}

mod gen3 {
    include!(r"\\?\D:\Projects\typenum_test/include.rs");
}

first two work, but the last causes an error

---

Windows canonical path
What does \\?\ mean when prepended to a file path

[MingweiSamuel]

It's this specific issue: rust-lang/rust#75075 (comment)

Error happens if OUT_DIR path is prefixed with \\?\ in which case / no longer works as a path separator on windows. Note that the \\?\ is required by windows if the path is longer than 260 characters

https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation

File I/O functions in the Windows API convert "/" to "" as part of converting the name to an NT-style name, except when using the "\?" prefix as detailed in the following sections.

[novacrazy]

I do actually kind of like the way that hydroflow PR handled the dynamic include path. That likely wouldn’t interfere with the docs.rs stuff like the previous system, which was the point of this PR.

Still, the issue as you described this is a pervasive issue with Windows/Rust in general and to patch it in a few specific crates is a bandaid at best.

[MingweiSamuel]

I will merge a mitigation fix in hydroflow to remove the \\?\ prefix which will allow it to work with / paths (when possible). I can also make a PR for this crate to re-introduce the per-platform path separator logic a la the hydroflow PR if you want

[paholg]

@MingweiSamuel I would welcome a PR.

My concern is if it falls to the same issues that my prior attempts had. Ideally, we would reproduce the various problematic setups in CI to ensure things work for everyone, but I'm not sure how realistic that is.