Hi all,<div><br></div><div>a while ago I submitted a pull request (see [1]) to add a "--output" switch to nbconvert which would allow the user to specify the output directory and/or output filename of the converted file. At the time I received a number of really helpful comments, but it turned out that my original implementation was too complicated and attempted to achieve too much, so it needed reworking.</div>
<div><br></div><div>Since then I have spent quite a bit of time thinking about it and reworking it, but I haven't uploaded a new PR because I continuously stumbled upon certain design questions that have kept me from coming up with a solution that I'd be happy with (and also I was flooded with work over the past couple of weeks). In the meantime, there has also been another PR [2] implementing very similar functionality (namely, specifying an output filename). However, even though in itself it looks good, I presume it will suffer from related problems when we try to extend it to support target directories.</div>
<div><br></div><div>So I figured it would be a good idea to gather some thoughts from the community before we rush into implementing a quick solution which is hard to improve later on (e.g. due to concerns about backward compatibility etc.).</div>
<div><br></div><div><div>There appear to be two main use cases for an --output flag:</div><div><br></div><div>(i) Specifying a target *filename* for the converted file.</div><div>(ii) Specifying a destination *directory* for the converted file.</div>
<div><br></div><div>It seems natural to handle these with the same flag. However, this raises a few questions:</div><div><br></div><div>(a) How do we decide whether the --output argument is a filename or a directory?</div>
<div><br></div><div>We could say that if the argument has a valid extension (e.g. '.rst' or '.html') then it should be interpreted as a filename, otherwise as a directory. A minor drawback might be that the user is then forced to use filenames whose suffix matches the output format, which is is probably ok in most cases but perhaps not always. Also, what if the --output argument has a valid extension but the "--format" argument specifies a different output format? For example:</div>
<div><br></div><div>   nbconvert --format rst --output foo.html foo.ipynb</div><div><br></div><div>I guess in this case the "--format" argument should have precedence, but then the logical thing to do interpret foo.html not a filename but as a directory, so the resulting output file would be foo.html/foo.rst. This is not very intuitive. Thus the next question is:</div>
<div><br></div><div>(b) Should we deduce the output format automatically from the filename extension or always rely on the --format switch? As mentioned, the former is quite intuitive in most cases but could sometimes lead to subtle annoyances. But either solution would force us to do a bit of "intelligent guesswork" as to whether the --output argument is supposed to be a filename or a directory.</div>
<div><br></div><div>So it seems that allowing the --output argument to be interpreted as either a filename or a directory would work well for 98% of the cases, but there are corner cases where it would behave in unexpected and/or annoying ways.</div>
<div><br></div><div>The alternative is to always and unconditionally interpret the --output argument as a directory and have another switch such as "--output-filename" to specify the filename. This is a slightly cleaner solution in that it doesn't require us to guess what the user intended to do. However, it seems unnecessarily awkward for most use cases. I for one would certainly quickly get annoyed by it.</div>
<div><br></div><div>In all this, we shouldn't forget that any solution should be easily extendable to handle the conversion of multiple files, à la:</div><div><br></div><div>   nbconvert --output foo/ *.ipynb</div><div>
<br></div><div>Any thoughts? It seems that it can't be *that* difficult to design a good CLI for such a simple task. Am I totally overthinking this? And how do other programs handle it?</div><div><br></div><div>Sorry for this long email and thanks in advance for any comments!</div>
<div><br></div><div>Best wishes,</div><div>Max</div></div><div><br></div><div><br></div><div>[1] <a href="https://github.com/ipython/nbconvert/pull/44">https://github.com/ipython/nbconvert/pull/44</a></div><div>[2] <a href="https://github.com/ipython/nbconvert/pull/62">https://github.com/ipython/nbconvert/pull/62</a></div>