Changes hashes to links in introduction

[lsf37]

These trigger the link checker on the docsite

[lsf37]

I also get a link check failure for the rustdoc reference to reply in root-task/spawn-thread.md -- it looks like the rustdoc is generated for MCS, but reply is only available on non-MCS.

[nspin]

I also get a link check failure for the rustdoc reference to reply in root-task/spawn-thread.md -- it looks like the rustdoc is generated for MCS, but reply is only available on non-MCS.

Ah. The issue here is that the root task part of the tutorial uses the non-MCS kernel, but I failed to consider this when opting to use the following shortcut for the build of the tutorial within the docsite's build system. The shortcut is that I just pointed rustdoc to the seL4 headers that ship with Microkit even for the root task docs.

I see three ways forward:

• Modify the root task part of the tutorial to use the MCS kernel
• Build the seL4 kernel (without MCS) as part of the docsite build system (this doesn't feel like such a satisfying solution)
• Move the tutorial repo to github.com/seL4 and have the docsite just link to https://sel4.github.io/seL4-rust-tutorial instead of building the tutorial as part of the docsite build system

[lsf37]

I see three ways forward:

• Modify the root task part of the tutorial to use the MCS kernel

I don't think we should change the content because of website presentation. It makes sense to start with the simpler API.

• Build the seL4 kernel (without MCS) as part of the docsite build system (this doesn't feel like such a satisfying solution)

How is the current rustdoc generated? (for the MCS version) Does that also need a kernel build?

• Move the tutorial repo to github.com/seL4 and have the docsite just link to https://sel4.github.io/seL4-rust-tutorial instead of building the tutorial as part of the docsite build system

Hm, difficult. I think we should move the tutorial over to the seL4 org in any case, but pointing to https://sel4.github.io/seL4-rust-tutorial is not so great, because the docsite will want more integration over time (I'm already injecting a back-link to the rest of the docsite into the sidebar js, for instance) and it will also be difficult to make sure the builds stay in sync if something changes on either side.

Could we point to the "real" rust doc of the released version instead? Or would that be hard to do/likely to break over time?

We could also remove just that one reference to avoid the problem.

[nspin]

How is the current rustdoc generated? (for the MCS version) Does that also need a kernel build?

Generating rustdoc for the seL4 crates has the same requirement from the environment that building them has, and that requirement is seL4 headers. For the Microkit/MCS side, that requirement is easier to satisfy because we can just download the Micorkit SDK binary distribution.

Could we point to the "real" rust doc of the released version instead? Or would that be hard to do/likely to break over time?

The downside of this approach is that the API the tutorial is based on and the HEAD API could be out of sync between when the rust-sel4 HEAD API is modified, before the tutorial is updated. But perhaps that's a tradeoff we're willing to make.

We could also remove just that one reference to avoid the problem.

This approach would mean pointing to the MCS API docs for the non-MCS part of the tutorial. To me, this would feel like another case of changing the content because of website presentation.

One decent solution that we haven't discussed yet would be pointing rustdoc links in the sel4.systems build not to sel4.github.io/rust-sel4/... but rather to sel4.github.io/sel4-rust-tutorial/rustdoc/.... That is, point to the rustdoc that is built and published by the tutorial repo's CI.

[nspin]

One decent solution that we haven't discussed yet would be pointing rustdoc links in the sel4.systems build not to sel4.github.io/rust-sel4/... but rather to sel4.github.io/sel4-rust-tutorial/rustdoc/.... That is, point to the rustdoc that is built and published by the tutorial repo's CI.

I've implemented this solution in lsf37/docs#2