Add html_root_url to documentation.

[wyattjsmith1]

When generating docs with cargo doc, it is often preferred to link external dependencies to existing hosted documentation (docs.rs) instead of regenerating the docs. Currently, running cargo doc leaves users with the option of either generating all documentation for gdnative (which is around 200M), or not including links to gdnative. Neither of these options is particularly desirable as one duplicates documentation and the other doesn't include document links.

Ideally, when users run cargo doc, they should only generate their own documentation, and have http links to external documentation on docs.rs (or wherever documentation is located).

Adding html_root_url to the project would allow users of this library to directly link to docs.rs: https://doc.rust-lang.org/rustdoc/the-doc-attribute.html?highlight=link#html_root_url.

Note: There is an open ticket to default to checking docs.rs, but that is old and doesn't seem to be actively developed: rust-lang/rust#42301

[ghost]

Thanks for the suggestion! Honestly, I'm not sure how "often preferred" and "ideal" that is. I myself, for instance, have always preferred all my documentation local, simply because it's faster that way, and 200M isn't really that large for a modern computer. Truth to be told, I never for once cared how large the documentation was.

As a result, I'm hesitant to support this proposal since it has the potential to be controversial. I would prefer to let this gather more opinions before doing anything. Are there any "big" libraries that have this behavior by default?

[wyattjsmith1]

Interesting. My perspective is coming from uploading the documentation to S3/Pages for viewing. For uploading reasons, you'd want it to be small, but I see where you are coming from. Seems like this is more of a rustdoc thing than a Godot thing.

…

On Mon, May 4, 2020, 20:17 toasteater ***@***.***> wrote: Thanks for the suggestion! Honestly, I'm not sure how "often preferred" and "ideal" that is. I myself, for instance, have always preferred all my documentation local, simply because it's faster that way, and 200M isn't really that large for a modern computer. Truth to be told, I never for once cared how large the documentation was. As a result, I'm hesitant to support this proposal since it has the potential to be controversial. I would prefer to let this gather more opinions before doing anything. Are there any "big" libraries that have this behavior by default? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#339 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEFGXF4T2RKQLWAC3OBV2K3RP6AM7ANCNFSM4MZFKIFQ> .

[ghost]

That's certainly a rare use case, then. You may make a local change on your own copy if you want to, but I'm afraid I can't see this getting into upstream, unless it's shown to be a more common practice among well-known crates, or if more users show their interest in it.

I'm keeping this open for now, but feel free to close the issue if you no longer need it in upstream.