Default output path of `nickel doc` is unexpected
gkleen opened this issue · comments
I was quite surprised that nickel doc by default wants to write it's output to a file (and accidentally commited one of those output files, even).
I think it would make more sense for nickel doc to emit to stdout by default?
I think the rationale is that it's more common to generate doc somewhere to then publish it or commit it, while it's more uncommon to post-process this documentation directly on the command line. Most documentation tools I know needs to generate multiple HTML files anyway - and nickel could do the same -, which don't make much sense to print on stdout.
That being said, I think we currently don't even print a message to say "Written doc in ...". Would that help to add such an output? Also, what I said might not apply to outputting the doc as json, where it might be indeed common to pipe the output to something else. I'm not sure yet it would be a good idea to have a different default behavior depending on the format, though.
A message stating the path of the output file would certainly have alleviated my surprise.
I think it also wouldn't seem out of place in other automations like the generation of html docs like you describe :)
P.S.: Sorry for the late response – seem to have had some imap issues that went unnoticed; getting to the other issues now, too…