Default output path of nickel doc is unexpected

[gkleen]

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?

[yannham]

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.

[gkleen]

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…