Don't put docs for rustc/syntax/etc on doc.rust-lang.org

[emberian]

People are getting confused about why these libraries are there. The only crate that should be documented and linked from the homepage is std.

[emberian]

cc @brson @steveklabnik

[steveklabnik]

It should be std, core, rustdoc, and test, I'd think?

[emberian]

core is behind the facade and isn't exposed, I thought? The rustdoc crate shouldn't be exposed as a library. test should be, though.

[mrec]

Possibly a separate issue, but where libraries exist both in rust-lang/rust and on crates.io, e.g. serialize/rustc-serialize, it's not at all obvious which is the master, i.e. where bug reports and PRs should be directed.

Would it be clearer if these things were handled by rust-lang/rust as submodules pointing to (forks of) the official version, in the same way that e.g. jemalloc is?

[steveklabnik]

@cmr but there are a significant number of users of Rust who will just use core and not std.

Why not rustdoc? Are we also sharing it through crates.io? I already have a crate that uses it as a library...

[steveklabnik]

@mrec always on the external one, and I don't think submodules are appropriate, as 1) they suck (:wink:) and 2) more seriously, they can diverge. some of them already have, a bit.

[emberian]

@steveklabnik Then they should be part of some "unstable", "internal", or some other page for these crates. I don't see a benefit to having the easily accessible from the front page, and this isn't the first time it has caused confusion.

[bluss]

If we hide rustc's documentation, that means we can remove it from the distribution as well right?

Rustc docs alone account for a whopping 150MB of the installation from a nightly, roughly 50% of the docs.

du -hs /usr/share/doc/rust/html/* | sort -h | tail
3,9M    /usr/share/doc/rust/html/libc
4,4M    /usr/share/doc/rust/html/implementors
6,7M    /usr/share/doc/rust/html/core
8,2M    /usr/share/doc/rust/html/rustc_llvm
9,7M    /usr/share/doc/rust/html/syntax
18M /usr/share/doc/rust/html/rustc_typeck
19M /usr/share/doc/rust/html/std
45M /usr/share/doc/rust/html/src
52M /usr/share/doc/rust/html/rustc_trans
84M /usr/share/doc/rust/html/rustc

[emberian]

@bluss I'd hope so, yes. Ideally librustc etc would not be in rustlib at all.

[aturon]

More generally, we need to be able to hide unstable APIs on the stable channel.

[tomjakubowski]

@aturon Shouldn't be too difficult to add a strip-unstable pass to rustdoc that the stable channel can use.

[reem]

It would be good if these and all other unstable APIs where still hosted somewhere, even if the stable channel docs didn't include them.

[tomjakubowski]

I presume that the stable docs will be hosted somewhere like http://doc.rust-lang.org/stable/, with beta and nightly releases hosted at appropriately different URLs.

[brson]

Can put these on nightly, but leave off of beta and stable.

[pnkfelix]

polish issue, 1.0 (but not 1.0 beta).

[bluss]

Thank you Cmr!

[lambda-fairy]

Would it be possible to keep the compiler internals docs somewhere?

I find them pretty useful for writing plugins and such, and I don't want to bootstrap rustc just for the docs.

[mikedilger]

I'm spending half the morning searching for the syntax crate docs to see how the ast changed so I can fix tojson_macros, and I can't find them presumably due to this issue.

I'm all for not confusing new users, but the docs ought to exist somewhere. These are currently not found under http://doc.rust-lang.org/nightly , but IMHO should be.

For now I'm reading the source code.

[steveklabnik]

@mikedilger we have a different issue tracking this, they will end up being hosted. However, in the meantime: http://manishearth.github.io/rust-internals-docs/