Rework rustdocs

[mkroening]

• Item visibility: Reduce crate exports #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.

kernel/src/drivers/virtio/virtqueue/mod.rs

Line 4 in a2f521f

//! [Split](structs.SplitVqueue.html) and [Packed](structs.PackedVqueue.html).

Another example is the structs getting moved to another file and the relative URL changing from structs.PackedVq.html to packed/structs.PackedVq.html

kernel/src/drivers/virtio/virtqueue/mod.rs

Line 111 in a2f521f

/// [PackedVq](structs.PackedVq.html) and [SplitVq](structs.SplitVq.html).

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. 👍