nbconvert: Output options -- names and documentataion

[dpsanders]

There needs to be documentation showing images of the same file run through the different output options with nbconvert.

The names of the different output options are rather opaque, for instance sphinx_howto makes little sense to someone from outside the world of Python documentation.

Thinking about the suggestion in #3701 that nbconvert should basically just take in the .ipynb and spit out the pdf, effectively the current latex, sphinx_howto and sphinx_manual become different style options for the PDF output.

In particular, sphinx_howto in this context would be an article in the LaTeX world, while sphinx_howto is a book. Thus pdf_article and pdf_book would be more appropriate names in this context.

In fact, we are indeed now converging, as in LaTeX .cls files, on the notion of different style specifications for the output. The internal mechanism to produce the final PDF (LaTeX directly versus Sphinx+LaTeX etc.) becomes irrelevant.

[dpsanders]

In fact, in the current list of nbconvert options:

'basic_html', 'full_html', 'latex', 'markdown', 'python', 'reveal', 'rst', 'sphinx_howto', 'sphinx_manual'

we can recognise 3 basic categories of options:

• fully-rendered output in its final form:
  (i) HTML: basic_html, full_html, reveal
  (ii) PDF: latex, sphinx_howto, sphinx_manual
• partially-rendered in a markup language:
  (i) markdown, rst
• with a different goal altogether, to still have a useful computational object: python

These 3 categories need to be differentiated in the command itself.
For example, there could be a syntax of the following kind:

ipython nbconvert --format="markup:rst" notebook.ipynb
ipython nbconvert --format="pdf:book" notebook.ipynb

In fact, I would regard the python option as in a different class on its own, more
nbstrip than nbconvert.

[minrk]

I agree that the flat list is probably the wrong choice, and that perhaps a more logical command-line UI would be --format=html --template=full, --format=latex --template=sphinx_howto, with logical defaults.

[minrk]

This is mostly a UI issue, since all of the output formats are actually just jinja templates, and it doesn't matter which ones are latex or HTML. You can also specify your own templates, which ignore everything else.

[dpsanders]

OK, I like the --template syntax; I proposed a more JSON-y one in my other open issue.

[ellisonbg]

I agree that the naming of things in nbconvert (formats, templates,
filters) needs a good going through before 1.0 - again, let's tackle this
at the dev meeting...

On Fri, Jul 19, 2013 at 8:32 PM, David Sanders notifications@github.comwrote:

OK, I like the --template syntax; I proposed a more JSON-y one in my
other open issue.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/3703#issuecomment-21284983
.

Brian E. Granger
Cal Poly State University, San Luis Obispo
bgranger@calpoly.edu and ellisonbg@gmail.com

[damianavila]

The --format and --template as a command-line UI sound good...

[jdfreder]

This was posted before the dev meeting CLI re-design. Export format is now specified with --to. --template can be used for specific output.