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

Mon Dec 3 10:21:39 EST 2012

Hi,

here is my wishful spec:

   nbconvert --output <folder or file> --format <html (default) | rst |
...> foo.ipynb

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
folder/foo.<fmt>
     case 2: if input is single file, output is file, then output is the
given file
     case 3: if input is multiple (folder or glob), output is a file, then
error out,
     case 4: if input is folder or glob, output is folder, then generate
multiple files as folder/*.<fmt>

Thanks,

Wen

On Mon, Dec 3, 2012 at 8:43 AM, Maximilian Albert <
maximilian.albert at gmail.com> wrote:

> 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
>
> _______________________________________________
> IPython-dev mailing list
> IPython-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev
>
>

-- 

Thanks,

- Wen
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20121203/dc75f13d/attachment.html>