Rework rustdocs

[mkroening]

• [x] Item visibility: https://github.com/hermitcore/libhermit-rs/pull/360
• [ ] Documentation of system calls
• [ ] Build docs with nightly features
• [ ] Link to docs.rs for dependencies

[nathanwhyte]

Hi Martin,

I'm taking a Virtualization course at UT Austin and we've been asked to contribute to open-source virtualization repositories for one of our projects. Could I take a shot at resolving this issue?

[mkroening]

Sure! More documentation is always welcome 👍

[cagatay-y]

There are quite a few links in the docs that were broken after code reorganization as the file URLs were invalidated. We can fix at least some of these by using intra-doc linking now that it's available. We can use cargo-deadlinks as a CI check to avoid such a situation in the future or at least for finding the broken links during the migration. We can also use cargo-intraconv to convert the old style links that currently work but are susceptible to breakage in a future refactoring.

[mkroening]

There are quite a few links in the docs that were broken after code reorganization as the file URLs were invalidated.

What kind of links are broken? Do you have examples?

I don't think the mentioned crates are necessary, but that may change once I understand the problem better.

[cagatay-y]

For example, in this line linked struct was renamed from SplitVqueue to SplitVq, which broke the link. https://github.com/hermit-os/kernel/blob/a2f521fe071d11a080071ab7565a789d983212fc/src/drivers/virtio/virtqueue/mod.rs#L4 Another example is the structs getting moved to another file and the relative URL changing from structs.PackedVq.html to packed/structs.PackedVq.html https://github.com/hermit-os/kernel/blob/a2f521fe071d11a080071ab7565a789d983212fc/src/drivers/virtio/virtqueue/mod.rs#L111

cargo-deadlinks lists 73 broken file:// URLs inside the target/doc/hermit directory after a cargo doc run with --document-private-items. I didn't look into all examples not to get too sidetracked.

To be clear, the two aforementioned packages would not be introduced as dependencies: I linked them partly to document them for later when I get a chance to look into the issue. Running cargo-intraconv after converting the existing links should not be necessary, as I would expect documentation added from now on to use intra-doc links from the get-go. cargo-deadlinks should also not be necessary, unless it turns out some of the file:// links cannot be converted to intra-doc links. Even in that case, it is not really necessary to make it a part of the CI workflow, since the kinds of changes that cause link breakages shouldn't be frequent.

[mkroening]

Okay, makes sense.

I was thinking the same. In the future, we'll make sure that we always use intra-doc links. 👍