Support for open local documentation without being in a project directory

[sandmor]

I want to simply open the terminal in home and type sensei whatever_crate and obtain the documentation locally, if it takes a while to compile it doesn't matter. Also, I suggest using a cache system for this, I thought about a cache "project" that compiles all the crates or something as whatever docs.rs does.

[edfloreshz]

Interesting idea!

Given that sensei aims to be as fast as possible by default, I might implement this as an opt-in option, mostly because having to download crates takes a long time.

Having a cache seems like a reasonable option, although there are still some limitations.

• When opening local documentation, querying is not available given that I haven't figured out a way to tell the browser to receive the ?search= parameter.

• Another problem is versioning, you'd have to download not only every crate you want to open but also every specific version. I could do this in the background but I don't want to lock cargo for so long.

Any ideas on how we could overcome these obstacles?

[sandmor]

1. I don't know sorry, pass a URL with parameters in Linux is so easy as without them, maybe in other OSes is different or is a limitation of the crate that you are using.
2. Well the recompiling for each version is inevitable but I don't understand "I don't want to lock cargo for so long", the lock is for project not global so if sensei introduces a "cache-holder project" if it's blocked doesn't affect the project in what you are working. Although I see an issue with a unique cache project and it's precisely the versioning, as you know you cannot have multiple crate versions on the same project with cargo doc so is needed to find another solution or use multiple projects, or maybe attempt to find how cargo manages to generate docs internally(suspect that some systematic call to rustc) and do the same, I think that cargo lets the heavy work to rustc so I hope this would not be so hard to implement.

[edfloreshz]

Passing the URL with parameters does seem to be failing due to library limitations, I'll investigate further. Regarding cargo locking, it does seem like cargo locks itself when executing operations at a global level.

Due to this limitation, I think sensei should ONLY download and compile crates for their requested version and store them in the cache, not download all of them all at once in the background, which could be counterproductive to the user.

As for the caching issue, perhaps storing different versions is possible. By creating ~/.sensei/cache/ and storing a folder for each crate with their respective versions inside, each of them being a different project.

Let me know your thoughts.

[sandmor]

I was not understanding you, with cache I don't refer to a background process but only that I don't have to recompile a crate various times, also, about blocking looks like cargo blocks globally in operations that involves the local crates repo, so Cargo.lock building and new crate downloading beyond that the compilation run only blocking the current project, but I too don't want spurious blocks, so I'm definitely not a favor of impose background process. About the cache structure for me is okay, although I would include a platform or target level after versioning. What really needs more thinking is how to manage cross-crate references that are pretty common in some crates, what do you think about? EDIT: Note that I'm not requesting the feature of cross-compiled docs only making room for them to avoid incompatibilities in the future.

[edfloreshz]

I "suggested" the background process as a way to fetch every version of a crate and store it in the cache so that you wouldn't have to wait for every single version to compile, but as I said earlier, blocking cargo isn't something I want, so if sensei is gonna have this feature, it's gonna have to compile every crate's version separately, assuming it's not in the cache already.

This will significantly reduce its speed but as it will be implemented as an option, I'm okay with that.

Good thinking with the platform level, although, I'm unfamiliar with cross-crate references, can you elaborate?

[sandmor]

I will take OutlineBuilder as an example if you click the src link it would link you to the source code of ttf-parser, another crate that is what I'm referring by "cross-crate references". This is not a problem when you generate docs for a sole project but can mess when you are treating with multiple versions of the same crate because cargo doc don't support it.

[edfloreshz]

Thanks for bringing it to my attention but this shouldn't be a problem. When generating local documentation, unless it's generated with the --no-deps flag, it should also generate documentation for the dependencies, which is locally present as well.

You're more than welcome to go ahead and try to implement it yourself, we could start with a basic cache system and parsing the arguments.

[sandmor]

Thank you, but the problem is how manage this when you move to different folders the crates, that broke the links, would us parse the HTML to redirect links

[edfloreshz]

Why would you move the folders? Every crate will document the crates it depends on and store them in the {crate}/target/doc/ directory. If 2 crates depend on the same crate, they will document it individually.

[sandmor]

1. For the cache structure
2. Because two versions of the same crate has the same path, cargo will generate the documentation for rand for 0.7.3 in the same path that for 0.6.1, for that multiple projects are needed and is unfriendly with the cache structure, so the only solution that I'm seeing is modifying the HTML files

[edfloreshz]

I think you're getting the wrong idea.

I'm thinking of creating a separate project for each version inside {crate}/{version}/ and then adding the requested crate as a dependency to Cargo.toml, then generate documentation from there.