[IPython-dev] [nbconvert] Specifying output filename/target directory: feedback needed

[Maximilian Albert]

Hi all,

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.

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.

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.).

There appear to be two main use cases for an --output flag:

(i) Specifying a target *filename* for the converted file.
(ii) Specifying a destination *directory* for the converted file.

It seems natural to handle these with the same flag. However, this raises a
few questions:

(a) How do we decide whether the --output argument is a filename or a
directory?

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:

   nbconvert --format rst --output foo.html foo.ipynb

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:

(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.

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.

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.

In all this, we shouldn't forget that any solution should be easily
extendable to handle the conversion of multiple files, à la:

   nbconvert --output foo/ *.ipynb

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?

Sorry for this long email and thanks in advance for any comments!

Best wishes,
Max


[1] https://github.com/ipython/nbconvert/pull/44
[2] https://github.com/ipython/nbconvert/pull/62
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20121203/af1114e6/attachment.html>