Add a cargo-doc command #254
Conversation
| pub fn doc(manifest_path: &Path, | ||
| options: &mut DocOptions) -> CargoResult<()> { | ||
| let mut src = PathSource::for_path(&manifest_path.dir_path()); | ||
| let _ = fs::rmdir_recursive(&manifest_path.dir_path().join("doc")); |
There was a problem hiding this comment.
This seems... bad. Someone creates doc/... with a variety of handwritten docs (not realising that this is cargo's build directory), and runs cargo doc, losing everything.
Maybe it should be target/doc too?
There was a problem hiding this comment.
I figured I'd duplicate what rust does in that doc is the build directory while src/doc is where handwritten documentation goes. Currently the build output of cargo doc (libraries and such) is placed in target/doc, but that could move to target/doc-build if we want.
I also figured that "target" implies "build artifacts from the compiler" less so than "documentation"
There was a problem hiding this comment.
The problem here is specifically the rmdir, since it is silently killing the whole directory; and it is very reasonable and fairly common to have a ./doc directory with handwritten docs. e.g.
- https://github.com/basho/riak/tree/develop/doc
- https://github.com/clutchski/coffeelint/tree/master/doc
- https://github.com/scottschiller/SoundManager2/tree/master/doc
- https://github.com/jemalloc/jemalloc/tree/dev/doc
- https://github.com/sympy/sympy/tree/master/doc
- https://github.com/ruby/ruby/tree/trunk/doc
- https://github.com/JuliaLang/julia/tree/master/doc
And there's a pile of projects using ./docs too. About half of the projects I randomly clicked on in Github's "showcases" had either ./doc or ./docs as (AFAICT) human written docs.
I think it's a really bad idea to force-remove the directory, destroying people's work, and it seems suboptimal to put machine generated output into it by default (although I agree that "target" seems a little weird for documentation).
There was a problem hiding this comment.
(We could encourage people to use ./src/doc, but having a command that mercilessly punishes deviation/mistakes by deleting it seems like a bad idea.)
|
I've updated with build output in |
|
A minor thing is that I don't think |
|
This doesn't handle doc tests, correct? |
|
@sfackler, not currently, but that's what I'd like to work on next for rustdoc integration. |
This is blocked until rust-lang/rust#15939 lands, but in the meantime I figured I could get some eyes on this to make sure I'm sane. Closes #130
This is blocked until rust-lang/rust#15939 lands, but in the meantime I figured I could get some eyes on this to make sure I'm sane. Closes rust-lang#130
This is blocked until rust-lang/rust#15939 lands, but in the meantime I figured I could get some eyes on this to make sure I'm sane.
Closes #130