Fix building docs on Windows

[jofas]

I believe this fixes #6625 by only building the io::bsd module on Unix machines, in accordance with #6625 (comment). Putting the #[cfg(unix)] outside of the cfg_aio! macro felt less intrusive, as the macro is also used in io::Interest.¹ I haven't yet tested this on Windows (or via cross-compilation).

While creating this PR I checked out the build logs from docs.rs and saw that the two Windows builds there are broken as well. I want to replicate how docs.rs builds the docs for Windows and fix them, too, so starting this PR as a draft.

I wonder if building the docs on Windows would be a good idea to add to CI, to guard against future regressions?

Footnotes

1. We should be able to build Interest on Windows with --cfg docsrs without problems. ↩

[mox692]

I wonder if building the docs on Windows would be a good idea to add to CI, to guard against future regressions?

Yes, this sounds good to me.

[jofas]

I wonder if we should abstract this into a macro that better describes what we are doing? Something like cfg_ignore_in_windows_docs!?

[jofas]

With these changes, the windows docs can be build with -C docsrs when cross-compiled in the crates-build-env container. There is still a bunch of warnings about broken links in the docs though, like this one, for example. Should I fix those as well? If yes, what would be the best approach here? I probably would just configure out the parts of the docs that don't build on Windows. The main downside of this would be that I make the source of the docs less readable when I replace the nice /// ... lines with cfg_attr!(unix, doc = ["..."]), or such.

[Darksonn]

Let's not try to fix the broken links. Can we silence the warnings?

[jofas]

We could add #![cfg_attr(windows, allow(rustdoc::broken_intra_doc_links)] to silence the broken link warnings.

[Darksonn]

Works for me.

[jofas]

This should allow documentation to be buildable on Windows when --cfg docsrs is enabled, but I don't like it. The #[cfg(docsrs)]-related conditional compilation feels a bit fragmented to me as is and this PR as it currently stands makes matters worse IMO. Especially after I found the doc module from #3760, where someone already started mocking Windows-specific items that are part of the public interface. If we were to mock all OS-specific types used throughout the library into such a module (not unlike the loom module), I think we could streamline conditional compilation and the quality of the documentation generated on Windows quite a bit. Would that be something the maintainers would be interested in?

On a side note, I'm not sure why the changes I made to the docs job of the CI workflow result in a Expected — Waiting for status to be reported docs check, especially because the "all systems go" and "basic checks" jobs succeeded.

[mox692]

To me, current changes looks fine.

On a side note, I'm not sure why the changes I made to the docs job of the CI workflow result in a Expected — Waiting for status to be reported docs check, especially because the "all systems go" and "basic checks" jobs succeeded.

Since this PR update the docs workflow, I guess the repository's branch protection settings is relevant here?
@Darksonn
Can you confirm this if you have time?

[Darksonn]

I've updated the branch protection rules.

Regarding improving docs support on Windows ... I guess we could. But we would need to repeat all the hacks we use to make windows docs show up on Linux.