NbConvertApp command line options not documented

[rlabbe]

Viewing nbconvertapp.py I see command line options such as inplace, clear-output, etc. Looking at the documentation for this app, usage.rst, I do not see any reference to these. A search on readthedocs reveal the changelog mentions them, but no one is going to go to a change log to understand what a command line will do.

I'm happy to try to edit usage.rst to fully document the command line options, but not sure on the workflow you are using. Should I just dive in and then issue a pull request?

[takluyver]

I don't think we explicitly try to document all the options in usage.rst - it's an overview rather than a comprehensive reference document.

You can see all the short command line options by running jupyter nbconvert --help, and all the config options that can be set at the command line with --help-all. The config options doc also lists all these, though it doesn't show the shorter command line flags yet - that's waiting on a new release of traitlets, so we can use ipython/traitlets#458.

[rlabbe]

Okay, but it is a one sentence change to add inplace. It currently reads:

This will open the notebook, execute it, capture new output, and save the result in :file:mynotebook.nbconvert.ipynb. By default, nbconvert will abort conversion if any exceptions occur during execution of a cell. If you specify --allow-errors (in addition to the --execute flag) then conversion will continue and the output from any exception will be included in the cell output.

You could append "If you specify "--inplace" (in addition to the --execute flag) the result will overwrite the notebook rather than save to :file:mynotebook.nbconvert.ipynb. " This is in the spirit of the paragraph, which already lists options you can use with --execute.

This seems useful to me, and not a degradation of the documentation.

[takluyver]

OK, PR welcome.

[t-makaro]

Closing as solved by #839 and #1048.