Something wrong with local cargo doc documents

[earthengine]

In a complicated project you will have different versions of the same crate in use and they may not be the latest due to restrictions in the ecosystem.

In this case doc.rs may not be the best option. I instead rely on local cargo doc documents.

I was assuming that the local documents should preform better than docs.rs, but I was wrong. In my crate I checked with cargo doc --open -p hyper:0.12:22, and the preformance were terrible: every time I switch between modules, there is a significant delay in the browser.

What is wrong with the local docs?

[jethrogb]

The search-index.js file keeps growing and growing every time you rebuild. Eventually it becomes so big that it takes a lot of CPU time to load it. Delete it (or run cargo clean) and then build the docs for all the crates you’re interested in, once.

[earthengine]

A complete rebuild from clean creates a search-index.js sized 6,806KB. And the performance remains the same.

[jethrogb]

Yeah that’s about the same size that I had issues with. Do you have a lot of dependencies? Try running cargo doc --no-deps and specify only the packages you’re interested in seeing the docs for.

[earthengine]

A normal flesh build will involve 3xx crates. This is the pretty normal number of dependencies when you use async/await, tokio, hyper and those staff.

[CAD97]

Cargo should probably add a thin dependencies mode for Rustdoc. That is, build docs for crates in the current workspace and crates they depend on directly but not transitively.

If it wanted to be real clever, add in transitive public dependencies of direct dependencies. The “important” part is to reduce the number of crates documented by removing the ones you’re unlikely to actually be looking for.

[Nemo157]

If it wanted to be real clever, add in transitive public dependencies of direct dependencies.

Yes, this sounds like a great usecase for the public/private dependency distinction (so much so that I’m going to steal it to mention on the tracking issue).

[Eh2406]

Yes, this sounds like a great usecase for the public/private dependency distinction

It is these other uses of this info that get me so excited about that rfc. I am working as hard as I can to get the cargo-resolver side done, but it is very stuck.

[Aaron1011]

@Eh2406: Are you still interested in help on the resolver side? I’d be happy to take a look.

[earthengine]

I would say, it would be greate if we can run cargo doc --current_crate that can build documents for everything

• in my crate; or
• refered by an extern crate statement within my lib.rs or main.rs file.

Because if I want to know about how to use things made by others, I first need to write an extern crate statement, right?

Also, have a way to coopporate with the rustup doc crates (alloc, core, proc_macro, std, test) would be greate. So I don’t have to run two seperate commands (cargo doc --open and rustup doc) to check things.

[earthengine]

Or better, if doc.rs can performs so good I didn’t see a reason why local documents can’t. Maybe there is a way to turn those "index"s off and just let the OS to figure out which file to load?

[jethrogb]

Or better, if doc.rs can performs so good I didn’t see a reason why local documents can’t.

docs.rs doesn’t let you search the documentation of 300 crates at once.

[earthengine]

Do the same in local then. When I need help. I usually don’t need to search. I know which crate I am looking for and I just want to know what methods I can call on a specific object.

So now the problem boils down to: can I turn the local search off as I never use it and it have performance impact?