doc: make root directory configurable

[jonhoo]

Problem

For cargo install, we have [install] root = "..", which allows the configuration (or a command-line flag) to dictate where the documentation should end up. It'd be nice to have a similar configuration option to allow customizing Cargo so that it directly generates its documentation into, say, a directory that's being served up by a local web server already.

Proposed Solution

Add a new root key to [doc], and a corresponding --root argument to cargo doc that dictates where the generated documentation should be placed.

Notes

No response

[basile-henry]

Should --root take precedence over --target-dir if both are specified in cargo doc?
Or is --root DIR intended to copy to DIR the generated docs that are (still) generated in <target-dir>/doc?

[jonhoo]

My instinct is the latter. Just like cargo install --root foo/ will still compile into target, cargo doc --root foo/ should do the same. Now, install gets to hardlink (when supported) the produced binary into root, which is harder with doc since it generates a directory tree, but a copy is probably fine.

[basile-henry]

My impression is that cargo install is slightly different to cargo doc. When installing a local package, it still compiles into <target-dir> because of the cargo build step it runs before installing a package.

As I understand it, cargo install always has a <root> to install to using a standard UNIX directory structure:

• <root>/bin for binaries
• <root>/lib for libraries
• <root>/share/man for man pages
• ...

cargo install has defaults for the <root> directory when no --root is specified (~/.cargo).

Currently, the cargo doc command is much closer to cargo build than cargo install when it comes to filesystem usage.
If the cargo doc --root option is omitted, it probably shouldn't act like cargo install where it defaults to some <root> directory, instead it should simply not copy the docs outside <target-dir>. Also, when --root is specified, should the docs be copied to a subdirectory (<root>/doc for example)?
How about giving the option a name like --copy-to to make it obvious the docs will still be in <target-dir>/doc and removing the ambiguity of where inside the <root> directory the docs should be copied to?

I'd be up for implementing this, I just wonder if it would get accepted since it adds a bit more complexity to cargo that will need to be maintained/documented: cargo doc --root <dir>, [doc] root = <dir>, and probably also a CARGO_DOC_ROOT env var, to replace something that is not too complicated to implement in bash:

cargo doc
cp -r target/doc/ <dir>

[jonhoo]

Yeah, that's a good point — I think I like --copy-to, though some bikeshedding on the exact name might be useful. For example, how about --publish-to (or --publish-into)?

I think this should introduce too much complexity, and is a worthwhile feature, so my personal guess is that a contribution would be welcomed, but I don't speak for the Cargo team, so they'd have to chime in :)

[basile-henry]

I like it! To bike-shed a little bit more, how about publish-dir (similar to target-dir)? While --<verb>-to works well for the CLI, I am now thinking it wouldn't work that well in the TOML config.

[basile-henry]

I am not entirely sure what the difference between cargo doc and cargo rustdoc is, but should this new configuration option be added to rustdoc as well? 🤔

[basile-henry]

Should the <publish-dir> be cleared before publishing? If not the directory might end up with outdated docs if they don't get overwritten properly.

I have implemented this feature at https://github.com/basile-henry/cargo/tree/basile-henry/doc-publish if you want to try it before I open a PR.

[jonhoo]

Hmm.. I think it should add to whatever is in that directory already so that I can, say, run cargo doc in two different crates whose --publish-dir is the same, and end up with the union of their docs.

[basile-henry]

I think it should add to whatever is in that directory already

Alright, that is the behaviour I went with. 👍

[epage]

As mentioned in #14791, we could possibly tie this into #6790