Comprehensive edit doc files for grammar and understanding #1389
Conversation
willingc
force-pushed
the
clarify-super
branch
from
948e27b
to
84e28c9
Compare
| Automating the data analysis in projects involving more than one notebook | ||
| is also possible. | ||
|
|
||
| Notebook execution can be done either from the command line or programmatically |
There was a problem hiding this comment.
I think we should add a note that nbclient is the natural successor for programmatic execution of notebooks, but that the interface remains here in nbconvert for extension and mixin of the preprocessor concept, and that papermill has a more extensive and robust command line interface than nbconvert for stand alone notebook execution. Many people using nbconvert execute don't know about those other options or when one is better to use.
| @@ -349,7 +349,7 @@ | |||
| "source": [ | |||
| "There are an endless number of transformations that you may want to apply to a notebook. In particularly complicated cases, you may want to actually create your own `Preprocessor`. Above, when we customized the list of preprocessors accepted by the `HTMLExporter`, we passed in a string -- this can be any valid module name. So, if you create your own preprocessor, you can include it in that same list and it will be used by the exporter.\n", | |||
| "\n", | |||
| "To create your own preprocessor, you will need to subclass from `nbconvert.preprocessors.Preprocessor` and overwrite either the `preprocess` and/or `preprocess_cell` methods." | |||
| "To create your own preprocessor, you will need to subclass from `nbconvert.preprocessors.Preprocessor` and overwrite either the `preprocess` and/or `preprocess_cell` methods. As of version 6.0, subclasses likely will need to call `super().preprocess_cell()` or something functionally equivalent to `NotebookClient.async_execute_cell`. In general, `super().preprocess_cell()` is best to minimize the complexity and subtlety of the multi-inheritance and overrides at play." | |||
There was a problem hiding this comment.
The super().preprocess_cell() or something functionally equivalent to 'NotebookClient.async_execute_cell'section only applies to ExecutePreprocessor. The more general case is that if the parent class does not raiseNotImplementedin it's definition then it's expected to havesuper().preprocess_cell(...)` called. As with all inheritance if you understand what the parent is doing and wish you can totally replace the calls and not call super.
| format given by the ``FORMAT`` string. | ||
|
|
||
| Default output format - HTML | ||
| ---------------------------- | ||
| The default output format is HTML, for which the ``--to`` argument may be | ||
| nbconvert's default output format is HTML, and the ``--to`` argument may be |
There was a problem hiding this comment.
Ahh this changed actually -- if you do not specify a --to you will get ValueError: Please specify an output format with '--to <format>'. I didn't realize we missed the doc update for that :/
There was a problem hiding this comment.
That probably means we need to find all the jupyter nbconvert and change them to jupyter nbconvert --to=html unless they have a to argument. I can take that after this merges if you like.
|
Thanks @willingc ! Many thanks for all the changes. |
|
@SylvainCorlay The changes are fine by me. Feel free to integrate if you have time. Otherwise, I will loop back later in the day. |
In trying to add (
Do subclasses need to call super().preprocess_cell() now?), I wound up cleaning up other pages.