rust-lang
Crate's docs.rs page irritatingly empty
Only after much irritation, I understood that using #![cfg(target_os = "windows")] is responsible for my crates https://docs.rs/win-beep/latest/win_beep/ and https://docs.rs/vcvars/latest/vcvars/ showing empty documentation. How must it be for a potential user of the crates?
I read that using #![cfg(target_os = "windows")] is better than causing compiler errors in a crate dependency (the crate being the dependency of others).
I now know that I can show the documentation by choosing an entry from the "Platform" drop-down menu (the entries are quite cryptic though, easily scaring you off). But I think docs.rs should, e.g., automatically choose a non empty "Platform" entry to be displayed.
Maybe it would be best to choose a platform that corresponds to what can be retrieved from the running browser (favoring 64 bits, of course, if this info can't be retrieved). And if that would result in an empty crate, show a message, if true, that there are other non-empty crate variants behind the "Platform" drop-down menu.
You can set which platforms you want the docs built for, and which is the default to show: https://docs.rs/about/metadata.
If it's easy to detect empty docs it may make sense to consider that to be a build failure for that platform (which would force overriding the default platforms); but I don't think it is something that we can really detect. We'd have to be parsing the html and checking the text content of the main section, which seems prone to false results for minor rustdoc output changes.
Thank you for the information.
Solving this may depend on improving rustdoc. I don't think they'd have something against it if it improves docs.rs.
Possibilities (not knowing the infrastructure):
- Add command line switch that prevents HTML output altogether on otherwise empty docs.
- Tool output equal or similar in nature to process exit code.
- An additional status file, similar to the lock file LibreOffice creates when having a document open.
- Use an HTML data attribute on the root tag:
<html data-docs-empty="true">. Easily checkable withRegex, since, also minding<!DOCTYPE>, it's at the very start. - Use an HTML
<meta>tag:<meta name="docs-empty" content="true">.
So it seems like this change would benefit doc-users, but only for crates where the author mistakenly didn't specify the doc-targets for the crate.
While I definitely see the advantage of this to help crate authors, I don't see how this would reliably work with the current rustdoc output, so this would definitely involve rustdoc side work.
I perhaps could see this when the JSON backend is stabilized, where we perhaps could query the structure when we store it anyways.
