I have a crate with some common types in it, and various crates that depend on it and use these common types. If I push the common types into the dependencies, I end up with a cyclic dependency graph, and cargo build will not function (which is a limitation I fully understand).
However, the documentation for the crate with common types would be more useful if I could link from the common types to some of the code in dependent crates that uses those types. Is there a way to have a cyclic dependency graph for documentation, but not for code, so that I can have [consuming_crate::consuming_function] linked from the documentation for pub struct CommonType? Note that consuming_function will already link to shared_crate::CommonType - it's the other direction I'd like to add.
I'm guessing no, because this would run into some of the same problems as building code with a cyclic dependency graph, but it's possible that I'm missing something.
If you going to publish your crates to crates.io (and docs.rs respectively), you can use direct links to the types like: [StructName](https://docs.rs/crate_name/latest/crate_name/struct.StructName.html)
I'm using similar approach in my crates, you can find some examples here.
Unfortunately, these are my employer's private crates, in our embedded system, and will not be published - plus, I'd want the docs to work offline as well as when I can get to docs.rs
Perhaps you're able to run your own private registry? I can suggest cratery, it has docs engine built-in, you can run it on some cheap VPS and restrict access to it. Of course, it doesn't solve the problem with full offline working docs. Although docs will build without problems but if you haven't internet access the links just won't open but you'll still be able just to find code references in around the docs.
Another workaround I just tested: you can run some simple file server for target/doc dir, I used python3 -m http.server 8000, in that case I was able to use links like:
It's not ideal solution but if you have to run it locally only and you're fine to add some script to run the server keep your docs on the one port it might be fine.
Hope at least one of this options will be useful for you
Our own private registry would help, but is a coordination problem I can't face dealing with - especially since we'd want to publish at least once per release, if not once per commit.
The problem I have is that I need docs to work in at least two places:
Our internal docs server, which has one URL per commit to our main branch.
cargo doc for offline use.
This only works if there's reliable relative links that I can use.
My current workaround is to just name the crates in the documentation, and rely on the reader having enough intelligence to realise that dependent_crate::function is a cross-crate reference despite not being linked. They can then use docs search to find it.
Unfortunately, that only works locally, and not with our docs server.
Thank you for all the great suggestions, though - I do appreciate the effort you've put in to trying to find a workaround for me, and I hope that someone else with a similar problem will benefit from your advice.
I assume your doc server creates urls for individual commits, but each commit contains docs of all crates as generated via cargo doc, so the search works cross-crates, right?
in that case, I think you can work around this by using the search query as your link target, like this:
