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.

1 Like
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

1 Like
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.

1 Like
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.

1 Like
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

1 Like
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?

1 Like