Make generated docs for Rust SDK available

[daviddrysdale]

Having improved the SDK doc comments, it would be nice if the cargo doc generated docs were online somewhere.

Possible options:

• Publish to https://crates.io : This feels premature and also there's an existing oak crate.
• Put generated files under (say) ./docs/sdk/: On its own this doesn't help much, because GitHub doesn't serve up .html files as HTML, just .md files. However…
• Put generated files under ./docs/sdk/ and turn on GitHub pages for docs/ on master : This would make the docs visible at https://project-oak.github.io/oak/sdk/; however, the Markdown files in docs/ would show up at https://project-oak.github.io/oak/ but would not render properly.
• Put generated files into a new gh-pages orphan branch.

I'd lean towards the last of these, with the generated docs stored in an sdk/ top-level directory so that it's possible to have a top-level index.html file that redirects to sdk/oak/index.html (because the top directory from cargo doc on the rust/ directory doesn't have an index.html file in it).

Example of how this would look here: https://daviddrysdale.github.io/oak

(Regardless of which mechanism we adopt, we should add something like a CI check to keep the generated docs up to date…)

[daviddrysdale]

@tiziano88 @michael-kernel-sanders @anghelcovici : thoughts/preferences?

[anghelcovici]

I like the example (hence, the last option), maybe we can use github actions to sync that?

[daviddrysdale]

Docs are now up at https://project-oak.github.io/oak. Leaving this issue open to cover setting some automated system for keeping them in sync with master.

[tiziano88]

Awesome! Could you add a link to that somewhere in the existing docs?

[daviddrysdale]

Links to generated docs added in #257

[daviddrysdale]

One wrinkle that will apply to any auto-regeneration system: rustdoc does not produce deterministic output, so it will not be safe to run a script on every commit and commit to gh-pages if anything has changed.

[tiziano88]

Is there anything left to do for this, apart from the auto-generation?

[daviddrysdale]

Still to do:

• Automatically update the gh-pages branch when master is updated (Use GitHub actions to build and publish Rust docs  #866).
• Remove docs for non-SDK, non-Runtime crates from the generated pages (Generated Rust docs include detritus from examples #765), which probably also includes…
  • Separate out content that is useful for developers on Oak, from developers of Oak.

[daviddrysdale]

Now #866 is in, might as well close this and defer to #765 for what's left.

[daviddrysdale]

Comment above about non-deterministic output looks like it still applies.

[daviddrysdale]

The doc generation has been deterministic for a while, so closing this in favour of #765