[IPython-dev] [nbconvert] Specifying output filename/target directory: feedback needed
Mon Dec 3 09:21:39 CST 2012
here is my wishful spec:
nbconvert --output <folder or file> --format <html (default) | rst |
default format is html, so --format is optional
default output is ./foo.html so --output is also optional
internally you determine if the value of output is a folder or file:
case 1: if input is single file, output is folder, then output is
case 2: if input is single file, output is file, then output is the
case 3: if input is multiple (folder or glob), output is a file, then
case 4: if input is folder or glob, output is folder, then generate
multiple files as folder/*.<fmt>
On Mon, Dec 3, 2012 at 8:43 AM, Maximilian Albert <
> Hi all,
> a while ago I submitted a pull request (see ) 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  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
> 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
> 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
> 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,
>  https://github.com/ipython/nbconvert/pull/44
>  https://github.com/ipython/nbconvert/pull/62
> IPython-dev mailing list
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the IPython-dev