Open mkroening opened 2 years ago
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?
Sure! More documentation is always welcome 👍
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.
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.
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.
Okay, makes sense.
I was thinking the same. In the future, we'll make sure that we always use intra-doc links. 👍