doc: cross-platform with target tags

[unkcpz]

ref #235

The goal of thi PR are:

• Showing keyutils and keyutils_persistent module doc in platform dropdown of x86_64_linux target (see fig below).
• tag for target OS so it is clear in what condition is the module avail.
• module section for apple-ios
• CI doc test for cross-platform
• portal list redirect to platform links (may not worth to do it)

The plans are to make the docs more friendly to easy redirect to correspond platform is build for each platform with all module section existed (the keyutils is missing for the linux at the moment). Then in the index page of the doc, having a list as the portal to different platform.

Allowed docs.rs to build for multiple OS.
The experimental doc_cfg feature is used to tag module for its targeting OS.

The caveat of this approach is not sure the docs.rs can properly display docs for all platform (I'll test with using docs.rs docker-compose to try locally, so I put it as draft). From what documented in https://docs.rs/about/metadata, and reference how it did in CI of security-framework crate. I think it will work.

I keep the build-xplot-docs.sh so it can be used to test the docs can be build for corresponding OS. It can maybe also server as the script for docs build test, if the approach of this PR adapted.

UPDATE: apparently after test using docs.rs docker-compose locally, using targets in [package.metadata.docs.rs] is NOT to have a single platform agnostic page to show all, but to have a platform dropdown that user can select which doc to look at (which is already there for the crate but I didn't realize, sorry about it). (see rust-lang/docs.rs#2749 for discussion)

Note for local docs.rs test:

• https://forge.rust-lang.org/docs-rs/add-dependencies.html is required for the pkg-config dependency.
• https://github.com/rust-lang/docs.rs

[unkcpz]

@brotskydotcom The pr is ready to be review.

For the last checkbox, maybe there is a good way to have some thing in the index crate docstring which I don't know (can follow up on the discussion. Maybe it also not so important to have the portal links in the index page of the docs. It can be done by [macOS doc](../../aarch64-apple-darwin/keyring/macos/index.html) but I tried with links in index page, which can be quite misleading, so I didn't move on with those changes.

[unkcpz]

Clearly there is a bug in CI file https://github.com/hwchen/keyring-rs/actions/runs/13550239365/workflow.
Thanks for turn that on. I'll give it a check.

[unkcpz]

I am not sure about the syntax for setting multiple targets. Since every change and test require approve to trigger the CI, @brotskydotcom please fill free to directly add commit and change this.

[unkcpz]

Nevermind, I test in my own crate, and works now with comma split target names. See the commit.

[brotskydotcom]

I don't want to add unstable features to the code, because it breaks stable and MSRV builds. I will add fuller discussion of this to the PR.

[brotskydotcom]

This feels like overkill. The linux-native-sync-persistent feature turns on the sync-secret-service feature so all you really need to do is add "doc" to the list of features on line 224.

[unkcpz]

You are right! simpler after using #[cfg_attr(docsrs, doc(cfg(target_os = "linux")))].

[brotskydotcom]

same comment as above, just add "doc" to line 243

[brotskydotcom]

I don't like adding unstable features to the build, for several reasons:

1. they will break standard and MSRV builds unless special (and confusing) configuration is used (see this issue for an extensive discussion of this).
2. they won't be used in the standard docs.rs build, so they won't show up in the standard docs.
3. they require all sorts of changes to the CI build scripts and for no good reason the specialized doc build isn't posted anywhere.

Since building the docs locally (with any target_os you can use locally) will get you the docs for all the modules you can use, and since rustdoc already posts the builds for all target os's except ios, I'm not sure we really need anything in this PR except to change the feature used by docs.rs to be linux-native-sync-persistent so all the linux modules are built.

If you really want the names of the other modules to be listed in every platform's build, the easiest way to do that would be to just have build on other platforms use the existing doc feature to include an additional module declaration that just contains a top-level comment saying "docs for this module available only when building for platform X". That at least gets people aware of the existence of the modules available on other platforms, and also how to find them.

[brotskydotcom]

I've moved this back to draft status while you consider feedback. Let me know what you think.

[unkcpz]

Thanks for the review!

I've moved this back to draft status while you consider feedback. Let me know what you think.

Sure!

they will break standard and MSRV builds unless special (and confusing) configuration is used (see rust-lang/rust#43781 for an extensive discussion of this).

That's true, so confine it in the scope where only docrs cfg is set should do the trick, as did in the tokio-rs by having #![cfg_attr(docsrs, feature(doc_cfg))]. I'll make the change if we agree on the next point.

they won't be used in the standard docs.rs build, so they won't show up in the standard docs.

This may not true, it is mentioned in https://docs.rs/about/builds, "All crates are built in a sandbox using the nightly release of the Rust compiler. ".

[brotskydotcom]

That's true, so confine it in the scope where only docrs cfg is set should do the trick, as did in the tokio-rs by having #![cfg_attr(docsrs, feature(doc_cfg))]. I'll make the change if we agree on the next point.

OK, I get it. And, yes, I didn't realize the standard docs build runs on nightly - thanks for pointing that out. Please go ahead and make the change and let's try again once you've fixed the build script.

[unkcpz]

I addressed all comments, ready for another go.

[brotskydotcom]

OK, great! This looks much cleaner, thanks.

There is still one typo in the ci script, please fix that.

Please rename the file build-xplat-docs.sh to test-docsrs-build.sh since that's actually what it's for.

[brotskydotcom]

Also please fix the CI script as suggested in the failed build logs.

[unkcpz]

Thanks for the nice review, requests addressed.

[unkcpz]

not sure why test_simultaneous_multiple_create_delete_single_thread failed, I guess it is independent of changes here?

[brotskydotcom]

not sure why test_simultaneous_multiple_create_delete_single_thread failed, I guess it is independent of changes here?

Yes, we see this from time to time due to resource starvation in the CI process. I just rerun in those cases.

[brotskydotcom]

Yes, very nice! Just one last little change and it's ready to pull, thanks!

[brotskydotcom]

Great, thanks for all the work on this. I'm going to pull it now, and then fix one more issue before releasing.

[brotskydotcom]

@unkcpz I just released 3.6.2 with this integrated - docs look great!! Thanks again for doing this.

[unkcpz]

Thank you for the review! @brotskydotcom I looking forward to contribute more!
We use the crate in a new feature of the tool of our team through the python wrapper. I'll report to #227 when the new feature merged and released.