Release changelog 5.4

docs/source/changelog.rst

@@ -8,56 +8,150 @@ Changes in nbconvert
 ---
 `5.4 on Github <https://github.com/jupyter/nbconvert/milestones/5.4>`__
 
-- Document ``--inplace`` command line flag. :ghpull:`839`
-- Don't remove empty cells by default :ghpull:`784`
-- Handle embedded images in html converter :ghpull:`780`
-- If set, use ``nb.metadata.authors`` for LaTeX author line :ghpull:`867`
+Significant Changes
+~~~~~~~~~~~~~~~~~~~
+
+Deprecations
+++++++++++++
+
+Python 3.3 support was dropped. The version of python is no longer common and new versions have many fixes and interface improvements that warrant the change in support.
+
+See :ghpull:`843` for implementation details.
+
+Changes in how we handle metadata
++++++++++++++++++++++++++++++++++
+
+There were a few new metadata fields which are now respected in nbconvert.
+
+``nb.metadata.authors`` metadata attribute will be respected in latex exports. Multiple authors will be added with ``,`` separation against their names.
+
+``nb.metadata.title`` will be respected ahead of ``nb.metadata.name`` for title assignment. This better matches with the notebook format.
+
+``nb.metadata.filename`` will override the default ``output_filename_template`` when extracting notebook resources in the ``ExtractOutputPreprocessor``. The attribute is helpful for when you want to consistently fix to a particular output filename, especially when you need to set image filenames for your exports.
+
+The ``raises-exception`` cell tag (``nb.cells[].metadata.tags[raises-exception]``) allows for cell exceptions to not halt execution. The tag is respected in the same way by `nbval <https://github.com/computationalmodelling/nbval>`_ and other notebook interfaces. ``nb.metadata.allow_errors`` will apply this rule for all cells. This feature is toggleable with the ``force_raise_errors`` configuration option.
+Errors from executing the notebook can be allowed with a ``raises-exception`` tag on a single cell, or the ``allow_errors`` configurable option for all cells. An allowed error will be recorded in notebook output, and execution will continue.
+If an error occurs when it is not explicitly allowed, a ``CellExecutionError`` will be raised.
+If ``force_raise_errors`` is True, ``CellExecutionError`` will be raised for any error that occurs while executing the notebook. This overrides both the ``allow_errors`` option and the ``raises-exception`` cell tags.
+
+See :ghpull:`867`, :ghpull:`703`, :ghpull:`685`, :ghpull:`672`, and :ghpull:`684` for implementation changes.
+
+Configurable kernel managers when executing notebooks
++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The kernel manager can now be optionally passed into the ``ExecutePreprocessor.preprocess`` and the ``executenb`` functions as the keyword argument ``km``. This means that the kernel can be configured as desired before beginning preprocessing.
+
+This is useful for executing in a context where the kernel has external dependencies that need to be set to non-default values. An example of this might be a Spark kernel where you wish to configure the Spark cluster location ahead of time without building a new kernel.
+
+Overall the ExecutePreprocessor has been reworked to make it easier to use. Future releases will continue this trend to make this section of the code more inheritable and reusable by others. We encourage you read the source code for this version if you're interested in the detailed improvements.
+
+See :ghpull:`852` for implementation changes.
+
+Surfacing exporters in front-ends
++++++++++++++++++++++++++++++++++
+
+Exporters are now exposed for front-ends to consume, including classic notebook. As an example, this means that latex exporter will be made available for latex 'text/latex' media type from the Download As interface.
+
+See :ghpull:`759` and :ghpull:`864` for implementation changes.
+
+Raw Templates
++++++++++++++
+
+Template exporters can now be assigned raw templates as string attributes by setting the ``raw_template`` variable.
+
+.. code-block::
+
+  class AttrExporter(TemplateExporter):
+      # If the class has a special template and you want it defined within the class
+      raw_template = """{%- extends 'rst.tpl' -%}
+  {%- block in_prompt -%}
+  raw template
+  {%- endblock in_prompt -%}
+      """
+  exporter_attr = AttrExporter()
+  output_attr, _ = exporter_attr.from_notebook_node(nb)
+  assert "raw template" in output_attr
+
+See :ghpull:`675` for implementation changes.
+
+New command line flags
+++++++++++++++++++++++
+
+The ``--no-input`` will hide input cells on export. This is great for notebooks which generate "reports" where you want the code that was executed to not appear by default in the extracts.
+
+An alias for ``notebook`` was added to exporter commands. Now ``--to ipynb`` will behave as ``--to notebook`` does.
+
+See :ghpull:`825` and :ghpull:`873` for implementation changes.
+
+Comprehensive notes
+~~~~~~~~~~~~~~~~~~~
+
+New Features
+++++++++++++
+- No input flag (``--no-input``) :ghpull:`825`
+- Add alias ``--to ipynb`` for notebook exporter :ghpull:`873`
 - Add ``export_from_notebook`` :ghpull:`864`
-- Fix minor typo in ``usage.rst`` :ghpull:`863`
+- If set, use ``nb.metadata.authors`` for LaTeX author line :ghpull:`867`
 - Populate language_info metadata when executing :ghpull:`860`
-- No need to check for the channels already running :ghpull:`862`
-- Update ``font-awesome`` version for slides :ghpull:`793`
 - Support for ``\mathscr`` :ghpull:`830`
-- Add note about local ``reveal_url_prefix`` :ghpull:`844`
-- Properly treat JSON data :ghpull:`847`
-- Move ``onlyif_cmds_exist`` decorator to test-specific utils :ghpull:`854`
 - Allow the execute preprocessor to make use of an existing kernel :ghpull:`852`
+- Refactor ExecutePreprocessor :ghpull:`816`
 - Update widgets CDN for ipywidgets 7 w/fallback :ghpull:`792`
-- Pass config to kernel from ExecutePreprocessor for configurable kernels :ghpull:`816`
-- Drop support for python 3.3 :ghpull:`843`
-- Include LICENSE file in wheels :ghpull:`827`
-- Check for too recent of pandoc version :ghpull:`814`
-- Ppdate log.warn (deprecated) to log.warning :ghpull:`804`
-- Cleanup notebook.tex during PDF generation :ghpull:`768`
 - Add support for adding custom exporters to the "Download as" menu. :ghpull:`759`
-- Removing more nose remnants via dependencies. :ghpull:`758`
-- Windows unicode error fixed, nosetest added to setup.py :ghpull:`757`
-- Added Ubuntu Linux Instructions :ghpull:`724`
 - Enable ANSI underline and inverse :ghpull:`696`
-- Remove offline statement and add some clarifications in slides docs :ghpull:`743`
 - Update notebook css to 5.4.0 :ghpull:`748`
 - Change default for slides to direct to the reveal cdn rather than locally :ghpull:`732`
-- Better content hiding; template & testing improvements :ghpull:`734`
+- Use "title" instead of "name" for metadata to match the notebook format :ghpull:`703`
+- Img filename metadata :ghpull:`685`
+- Added MathJax compatibility definitions :ghpull:`687`
+- Per cell exception :ghpull:`684`
+- Simple API for in-memory templates :ghpull:`674` :ghpull:`675`
+- Set BIBINPUTS and BSTINPUTS environment variables when making PDF :ghpull:`676`
+- If ``nb.metadata.title`` is set, default to that for notebook :ghpull:`672`
+
+Deprecations
+++++++++++++
+- Drop support for python 3.3 :ghpull:`843`
+
+Fixing Problems
++++++++++++++++
+- Fix api break :ghpull:`872`
+- Don't remove empty cells by default :ghpull:`784`
+- Handle attached images in html converter :ghpull:`780`
+- No need to check for the channels already running :ghpull:`862`
+- Update ``font-awesome`` version for slides :ghpull:`793`
+- Properly treat JSON data :ghpull:`847`
 - Skip executing empty code cells :ghpull:`739`
+- Ppdate log.warn (deprecated) to log.warning :ghpull:`804`
+- Cleanup notebook.tex during PDF generation :ghpull:`768`
+- Windows unicode error fixed, nosetest added to setup.py :ghpull:`757`
+- Better content hiding; template & testing improvements :ghpull:`734`
 - Fix Jinja syntax in custom template example. :ghpull:`738`
 - Fix for an issue with empty math block :ghpull:`729`
-- Use "title" instead of "name" for metadata to match the notebook format :ghpull:`703`
+- Add parser for Multiline math for LaTeX blocks :ghpull:`716` :ghpull:`717`
+- Use defusedxml to parse potentially untrusted XML :ghpull:`708`
+- Fixes for traitlets 4.1 deprecation warnings :ghpull:`695`
+
+Testing, Docs, and Builds
++++++++++++++++++++++++++
+- A couple of typos :ghpull:`870`
+- Add python_requires metadata. :ghpull:`871`
+- Document ``--inplace`` command line flag. :ghpull:`839`
+- Fix minor typo in ``usage.rst`` :ghpull:`863`
+- Add note about local ``reveal_url_prefix`` :ghpull:`844`
+- Move ``onlyif_cmds_exist`` decorator to test-specific utils :ghpull:`854`
+- Include LICENSE file in wheels :ghpull:`827`
+- Added Ubuntu Linux Instructions :ghpull:`724`
+- Check for too recent of pandoc version :ghpull:`814` :ghpull:`872`
+- Removing more nose remnants via dependencies. :ghpull:`758`
+- Remove offline statement and add some clarifications in slides docs :ghpull:`743`
 - Linkify PR number :ghpull:`710`
-- Img filename metadata :ghpull:`685`
 - Added shebang for python :ghpull:`694`
 - Upgrade mistune dependency :ghpull:`705`
-- Added MathJax compatibility definitions :ghpull:`687`
-- Fixes for traitlets 4.1 deprecation warnings :ghpull:`695`
-- Per cell exception :ghpull:`684`
 - add feature to improve docs by having links to prs :ghpull:`662`
-- Raw template as settable attribute :ghpull:`675`
 - Update notebook CSS from version 4.3.0 to 5.1.0 :ghpull:`682`
-- Update notebook CSS from 4.3.0 to 5.1.0 :ghpull:`1`
-- Set BIBINPUTS and BSTINPUTS environment variables when making PDF :ghpull:`676`
-- If ``nb.metadata.title`` is set, default to that for notebook :ghpull:`672`
 - Explicitly exclude or include all files in Manifest. :ghpull:`670`
 
-
 5.3.1
 -----
 `5.3.1 on Github <https://github.com/jupyter/nbconvert/milestones/5.3.1>`__