edit doc source files for grammar and understanding

docs/autogen_config.py

@@ -2,7 +2,7 @@
 """
 autogen_config.py
 
-Create config_options.rst, a Sphinx documentation source file.
+Creates config_options.rst, a Sphinx documentation source file.
 Documents the options that may be set in nbconvert's configuration file,
 jupyter_nbconvert_config.py.
 

docs/source/execute_api.rst

@@ -9,72 +9,109 @@ nbconvert provides a convenient way to execute the input cells of an
 as a .ipynb file.
 
 In this section we show how to execute a ``.ipynb`` notebook
-document saving the result in notebook format. If you need to export
+document and save the result in notebook format. If you need to export
 notebooks to other formats, such as reStructured Text or Markdown (optionally
 executing them) see section :doc:`nbconvert_library`.
 
-Executing notebooks can be very helpful, for example, to run all notebooks
-in Python library in one step, or as a way to automate the data analysis in
-projects involving more than one notebook.
+Executing notebooks can be helpful functionality for some use cases.
+For example, nbconvert can run all notebooks in a folder in one step.
+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
+using the Python API interface.
 
 Executing notebooks from the command line
 -----------------------------------------
-The same functionality of executing notebooks is exposed through a
-:doc:`command line interface <usage>` or a Python API interface.
-As an example, a notebook can be executed from the command line with::
+The same functionality of executing notebooks in Jupyter Notebook, JupyterLab,
+or other front-end applications is available through a
+:doc:`command line interface <usage>`.
 
-    jupyter nbconvert --to notebook --execute mynotebook.ipynb
+To execute a notebook from the command line, enter the command below and
+specify the command line options for the file to execute (``--execute``)
+and the output (``--to``)::
 
-Executing notebooks using the Python API interface
---------------------------------------------------
-This section will illustrate the Python API interface.
+    jupyter nbconvert --to notebook --execute mynotebook.ipynb
 
-Example
-~~~~~~~
+To find available command line options, enter:
 
-Let's start with a complete quick example, leaving detailed explanations
-to the following sections.
+    jupyter nbconvert --help
 
-**Import**: First we import nbconvert and the `ExecutePreprocessor`
+Executing notebooks using the Python API interface
+--------------------------------------------------
+Using nbconvert's Python API interface enables programmatic execution
+of notebooks. This satisfies the use case where notebooks could
+be executed from applications which import the nbconvert package.
+
+A complete example
+~~~~~~~~~~~~~~~~~~
+
+To better understand how to use nbconvert's Python API, let's start with a complete example.
+This example illustrates the basics and leaves more in-depth explanations
+to later sections. The basic steps include:
+
+- import
+- load
+- configure
+- execute/run (preprocess)
+- save
+
+Import
+++++++
+First we import nbconvert and the `ExecutePreprocessor`
 class::
 
     import nbformat
     from nbconvert.preprocessors import ExecutePreprocessor
 
-**Load**: Assuming that ``notebook_filename`` contains the path of a notebook,
-we can load it with::
+Load
+++++
+Assuming that ``notebook_filename`` contains the path of a notebook,
+use the following to open it::
 
     with open(notebook_filename) as f:
         nb = nbformat.read(f, as_version=4)
 
-**Configure**: Next, we configure the notebook execution mode::
+Configure
+++++++++
+
+Next, we configure the notebook execution mode::
 
     ep = ExecutePreprocessor(timeout=600, kernel_name='python3')
 
-We specified two (optional) arguments ``timeout`` and ``kernel_name``, which
-define respectively the cell execution timeout and the execution kernel.
+We specified two (optional) arguments ``timeout``, the cell execution
+timeout, and ``kernel_name``, the execution kernel's name.
 
     The option to specify **kernel_name** is new in nbconvert 4.2.
     When not specified or when using nbconvert <4.2,
     the default Python kernel is chosen.
 
-**Execute/Run (preprocess)**: To actually run the notebook we call the method
+Execute/Run (preprocess)
+++++++++++++++++++++++++
+To actually run the notebook we call the method
 :meth:`~ExecutePreprocessor.preprocess`::
 
     ep.preprocess(nb, {'metadata': {'path': 'notebooks/'}})
 
-Hopefully, we will not get any errors during the notebook execution
+Hopefully, notebook execution will not get any errors
 (see the last section for error handling). Note that ``path`` specifies
 in which folder to execute the notebook.
 
-**Save**: Finally, save the resulting notebook with::
+Save
+++++
+Finally, save the resulting notebook with::
 
     with open('executed_notebook.ipynb', 'w', encoding='utf-8') as f:
         nbformat.write(nb, f)
 
-That's all. Your executed notebook will be saved in the current folder
+Your executed notebook will be saved in the current folder
 in the file ``executed_notebook.ipynb``.
 
+Summary
++++++++
+The above example covers the fundamental steps of using nbconvert's Python API:
+import, load, configure, execute/run, save
+
 Execution arguments (traitlets)
 -------------------------------
 
@@ -112,8 +149,12 @@ maintain consistency: we can just run a notebook twice, specifying first
 Handling errors and exceptions
 ------------------------------
 
-In the previous sections we saw how to save an executed notebook, assuming
-there are no execution errors. But, what if there are errors?
+The previous sections covered how to save an executed notebook, assuming
+no execution errors occur. But, what if there are errors?
+
+The options for handling errors are flexible and include execution until
+the first error and save, handling errors during execution, and executing
+and then saving all errors. 
 
 Execution until first error
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -130,7 +171,8 @@ and includes a full stack-trace and error (which can help debugging).
 
 Handling errors
 ~~~~~~~~~~~~~~~
-A useful pattern to execute notebooks while handling errors is the following::
+A useful pattern to execute notebooks while handling errors uses a
+try/except/finally block such as in the following::
 
     from nbconvert.preprocessors import CellExecutionError
 
@@ -146,7 +188,7 @@ A useful pattern to execute notebooks while handling errors is the following::
         with open(notebook_filename_out, mode='w', encoding='utf-8') as f:
             nbformat.write(nb, f)
 
-This will save the executed notebook regardless of execution errors.
+This approach will save the executed notebook regardless of execution errors.
 In case of errors, however, an additional message is printed and the
 `CellExecutionError` is raised. The message directs the user to
 the saved notebook for further inspection.
@@ -155,8 +197,8 @@ Execute and save all errors
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 As a last scenario, it is sometimes useful to execute notebooks which raise
 exceptions, for example to show an error condition. In this case, instead of
-stopping the execution on the first error, we can keep executing the notebook
-using the traitlet ``allow_errors`` (default is False). With
+stopping the execution on the first error, we can keep executing the notebook.
+To do this we set the traitlet ``allow_errors`` (default is False) to True. With
 ``allow_errors=True``, the notebook is executed until the end, regardless of
 any error encountered during the execution. The output notebook, will contain
 the stack-traces and error messages for **all** the cells raising exceptions.
@@ -170,8 +212,8 @@ the state of all the widgets can be stored in the notebook's metadata.
 This allows rendering of the live widgets on for instance nbviewer, or when
 converting to html.
 
-We can tell nbconvert to not store the state using the ``store_widget_state``
-argument::
+Setting the ``store_widget_state`` argument determines whether or not to
+save the widget's state. We can tell nbconvert to not store the state using::
 
     jupyter nbconvert --ExecutePreprocessor.store_widget_state=False --to notebook --execute mynotebook.ipynb
 

docs/source/index.rst

@@ -41,6 +41,9 @@ batch of notebook files to another format.
    removing_cells
    execute_api
 
+..
+   Comment: config_options is created by running autogen_config.py
+
 .. toctree::
    :maxdepth: 2
    :caption: Configuration

docs/source/latex_citations.rst

@@ -1,12 +1,12 @@
 LaTeX citations
 ===============
 
-``nbconvert`` now has support for LaTeX citations. With this capability you
+``nbconvert`` has support for LaTeX citations. With this capability you
 can:
 
-* Manage citations using BibTeX.
-* Cite those citations in Markdown cells using HTML data attributes.
-* Have ``nbconvert`` generate proper LaTeX citations and run BibTeX.
+    * Manage citations using BibTeX.
+    * Cite those citations in Markdown cells using HTML data attributes.
+    * Have ``nbconvert`` generate proper LaTeX citations and run BibTeX.
 
 For an example of how this works, please see the `citations example`_ in
 the nbconvert-examples_ repository.

docs/source/removing_cells.rst

@@ -6,8 +6,10 @@ Removing cells, inputs, or outputs
 When converting Notebooks into other formats, it is possible to
 remove parts of a cell, or entire cells, using preprocessors.
 The notebook will remain unchanged, but the outputs will have
-certain pieces removed. Here are two primary ways to accomplish
-this.
+certain pieces removed. The two primary ways for removal are:
+
+    - Using cell tags
+    - Using regular expressions
 
 Removing pieces of cells using cell tags
 ----------------------------------------
@@ -50,7 +52,7 @@ is a list of strings. For each cell, this preprocessor checks whether
 the cell contents match any of the strings provided in ``patterns``.
 If the contents match any of the patterns, the cell is removed from the notebook.
 
-For example, execute the following command to convert a notebook to html
+For example, executing the following command will convert a notebook to html
 and remove cells containing only whitespace:
 
 .. code-block:: bash

docs/source/usage.rst

@@ -1,18 +1,18 @@
 .. highlight:: none
 
-Using as a command line tool
-============================
+Using the command line tool
+===========================
 
-The command-line syntax to run the ``nbconvert`` script is::
+``nbconvert`` can be run from the command line using::
 
   $ jupyter nbconvert --to FORMAT notebook.ipynb
 
-This will convert the Jupyter notebook file ``notebook.ipynb`` into the output
+For example, nbconvert will convert the Jupyter notebook file ``notebook.ipynb`` into the output
 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
 omitted::
 
   $ jupyter nbconvert notebook.ipynb
@@ -206,7 +206,7 @@ Markdown
 .. _convert_ascii:
 
 Ascii
-~~~~~~~~
+~~~~~
 * ``--to asciidoc``
 
   Ascii output.
@@ -301,18 +301,19 @@ the output may be sent to standard output with::
 
 Converting multiple notebooks
 -----------------------------
-Multiple notebooks can be specified from the command line::
+Multiple notebooks can be specified from the command line for execution::
 
   $ jupyter nbconvert notebook*.ipynb
   $ jupyter nbconvert notebook1.ipynb notebook2.ipynb
 
-or via a list in a configuration file, say ``mycfg.py``, containing the text:
+A list in a configuration file may also be used. For example, in a config file ``mycfg.py``,
+a list of notebooks can be specified:
 
 .. code-block:: python
 
   c = get_config()
   c.NbConvertApp.notebooks = ["notebook1.ipynb", "notebook2.ipynb"]
 
-and using the command::
+and then executed using the command::
 
   $ jupyter nbconvert --config mycfg.py