API documentation for unstable internal crates


#1

I was trying to find API documentation for libtest recently. It’s there in the code, but not generated by ./x.py doc, and I can’t find it on the web anywhere (I only found a chapter in the unstable book). Also, trying to use cargo doc on that crate itself failed (internal libraries are special).

So, is there a way of generating API documentation for unstable internal crates?


#2

There’s a flag you can pass when building rust to do it, I forget its name.
@manishearth knows!


#3

The doc is on the web too, https://manishearth.github.io/rust-internals-docs/rustc/ ; crate test in the sidebar.


#4

I think this is what you need for x.py to document the internals: https://github.com/rust-lang/rust/blob/master/config.toml.example#L117


#5

I’m also serving the internal docs using GitHub Pages and have a cron job set up so that they get rebuilt once or twice a day.

Last I checked @Manishearth’s docs are generated manually and when I wanted to use them they were a bit outdated, prompting me to automate the process.


#6

@michael-F-Bryan, @manishearth
Shouldn’t such compiler-related documentation be in the Rust-lang repo, rather than two personal ones (who are not even in sync!)
Is there a particular reason it isn’t/can’t be?


#7

Yes, it should. Someone needs to do the work of setting that up in Rust’s automation.


#8

There’s an issue open for this. I was going to take a crack at it, but the task seemed a bit daunting.

https://github.com/rust-lang/rust/issues/29893


#9

After reading about the respectable amount of infrastructure (apparently) involved in nightly rust builds, I can see what you mean, although manishearth seems to break it down nicely?

How accessible is the automation to “newcomers”? And how much mentoring capacity is available?