Open Bug 1428139 Opened 7 years ago Updated 2 years ago

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

Categories

(Developer Infrastructure :: Source Documentation, enhancement)

Product:
Developer Infrastructure
Component:
Source Documentation
Type:
enhancement

Tracking

(Not tracked)

People

(Reporter: nika, Unassigned, Mentored)

References

(Blocks 2 open bugs)

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
Blocks: first-class-docs
Component: General → Generated Documentation
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.

Product: Firefox Build System → Developer Infrastructure
Severity: normal → S3

Recognizing that hosting is not the main effort here, searchfox could host the rendered docs which could enable a high confidence[1] "go to rustdoc for FOO" context menu option in searchfox and appropriate annotations in search results.

1: High confidence in this case meaning that searchfox could gate the availability of the context menu on having downloading the rendered rustdoc directly corresponding to the indexed revision and extracted it. It would of course always be possible for searchfox to blindly generate links to the docs hosted elsewhere, it's just harder to guarantee invariants about the links.

When trying to compile the docs on my linux setup I get build errors regarding std::os::windows not being available. But building the docs on windows might work (I don't have a build environment available for that, but we could use the CI).

BUILDCONFIG_RS=/home/user/dev/gecko/obj-x86_64-pc-linux-gnu/build/rust/mozbuild/buildconfig.rs MOZ_TOPOBJDIR=obj-x86_64-pc-linux-gnu/ cargo doc --workspace

Andrew, is that enough for you to host the docs on searchfox? I think that'd be great. I have no experience in CI, so couldn't try running that command (modified to the windows environment) there yet. I would like to help with this bug if further work is required and someone could mentor me (as this is also marked as good-first-bug).

Flags: needinfo?(bugmail)

(I'm no longer working on searchfox, clearing need-info.)

Flags: needinfo?(bugmail)
You need to log in before you can comment on or make changes to this bug.