Open Bug 1428139 Opened 4 years ago Updated 2 years ago

Run `rustdoc` on libgkrust, and host the results somewhere

Categories

(Firefox Build System :: Documentation Infrastructure, enhancement)

enhancement
Not set
normal

Tracking

(Not tracked)

People

(Reporter: nika, Unassigned, Mentored)

References

(Blocks 1 open bug)

Details

(Keywords: good-first-bug, Whiteboard: [lang=python])

It would be really handy to have the `rustdoc` for libgkrust hosted somewhere. This would contain the documentation for `gkrust`, every rust crate in the source tree, and every vendored rust crate which we depend on, which could be very handy for rust developers.

For example, when writing the `nsstring` crate, I tried to make sure that the crate had good documentation when rendered with rustdoc, but that isn't hosted anywhere right now as far as I know.

It might also be good to add a `mach doc rust` or similar mach command (I believe mach doc runs jsdoc right now?) which runs rustdoc and generates documentation in the objdir so that it is easy to run rustdoc on libgkrust locally.

To make it easier to learn how to use `xpcom` in rust when I land my bindings in bug 1293362, I'm hoping to generate good rustdoc documentation for the new xpcom crate, and that will be much more useful if there's an easy way to view it.
It is trivial to add a task to CI that runs `rustdoc`. That task would likely be defined at https://hg.mozilla.org/mozilla-central/file/tip/taskcluster/ci/source-test/doc.yml.

The tricky parts are:

* Getting a Rust toolchain in the execution environment. We may need to modify the Docker image. However, the Rust toolchain is pinned in the source repo and there is TaskCluster magic to set up task dependencies and build system code to download an appropriate Rust toolchain.
* Uploading the docs somewhere. We currently upload the Sphinx docs to an S3 bucket. There is a TaskCluster "secret" containing AWS credentials for that bucket. We'll need to figure out an appropriate destination path in the S3 bucket for the docs.

Dustin or I can help with the latter bit. But the first step is to get a task generating the docs: we can worry about upload after.

glandium: are the toolchain task dependencies in such a state to facilitate easily using them here? Or would it be simpler to just one-off `rustup install` in a Dockerfile until they are?
Flags: needinfo?(mh+mozilla)
You can't use toolchain task artifacts from Dockerfiles, because of the kind dependencies (toolchains depend on docker images). What you can do is install the artifacts from the doc task instead of "hardcoding" it in the docker image. That's what we do for everything.
Flags: needinfo?(mh+mozilla)
Product: Core → Firefox Build System
Component: General → Generated Documentation
Duplicate of this bug: 1646627
Mentor: sledru
Keywords: good-first-bug
Whiteboard: [lang=python]

FWIW, you can locally generate and view rustdocs for a crate in m-c like so:

cd xpcom/rust/xpcom
MOZ_TOPOBJDIR=/path/to/objdir cargo doc
cd -
firefox target/doc/xpcom/index.html

Which is better than nothing.

You need to log in before you can comment on or make changes to this bug.