diff --git a/.circleci/config.yml b/.circleci/config.yml index dc13d7cbe..cbc129c48 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -54,7 +54,7 @@ jobs: - run: name: Building HTML command: | - python3 setup.py build_sphinx -W -b html + python3 setup.py build_sphinx -b html - store_artifacts: name: Uploading HTML files @@ -64,7 +64,7 @@ jobs: - run: name: Building LaTeX command: | - python3 setup.py build_sphinx -W -b latex + python3 setup.py build_sphinx -b latex - run: name: Building PDF @@ -80,7 +80,7 @@ jobs: - run: name: Checking for broken links command: | - python3 setup.py build_sphinx -W -b linkcheck + python3 setup.py build_sphinx -b linkcheck workflows: version: 2 diff --git a/docs/source/api/exporters.rst b/docs/source/api/exporters.rst index 3dfdfbaf9..585d8c7c1 100644 --- a/docs/source/api/exporters.rst +++ b/docs/source/api/exporters.rst @@ -47,7 +47,7 @@ Specialized exporter classes ---------------------------- The `NotebookExporter` inherits directly from -`Exporter`, while the other exporters listed here +``Exporter``, while the other exporters listed here inherit either directly or indirectly from `TemplateExporter`. diff --git a/docs/source/api/filters.rst b/docs/source/api/filters.rst index 4f559d5c2..c9d128121 100644 --- a/docs/source/api/filters.rst +++ b/docs/source/api/filters.rst @@ -3,7 +3,7 @@ Filters ======= -Filters are for use with the `TemplateExporter` exporter. +Filters are for use with the ``nbconvert.exporters.templateexporter.TemplateExporter`` exporter. They provide a way for you transform notebook contents to a particular format depending on the template you are using. For example, when converting to HTML, you would want to use the `ansi2html()` function to convert ANSI colors (from diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst index b31056ef2..e9b565caa 100644 --- a/docs/source/architecture.rst +++ b/docs/source/architecture.rst @@ -5,16 +5,16 @@ Architecture of nbconvert ========================= This is a high-level outline of the basic workflow, structures and objects in nbconvert. -Specifically, this exposition has a two-fold goal: - - #. to alert you to the affordances available for customisation or direct contributions +Specifically, this exposition has a two-fold goal: + + #. to alert you to the affordances available for customisation or direct contributions #. to provide a map of where and when different events occur, which should aid in tracking down bugs. - + A detailed pipeline exploration =============================== -Nbconvert takes in a notebook, which is a JSON object, and operates on that object. +Nbconvert takes in a notebook, which is a JSON object, and operates on that object. This can include operations that take a notebook and return a notebook. For example, that operation could be to execute the notebook as though it were a continuous script; if it were executed ``--in-place`` then it would overwrite the current notebook. @@ -36,21 +36,21 @@ Markdown cells and raw NbConvert cells do not have analogous substructure. The template's structure then can be seen as a mechanism for selecting content on which to operate. Because the template operates on individual cells, this has some upsides and drawbacks. -One upside is that this allows the template to have access to the individual cell's metadata, which enables intelligently transforming the appropriate content. -The transformations occur as a series of replacement rules and filters. +One upside is that this allows the template to have access to the individual cell's metadata, which enables intelligently transforming the appropriate content. +The transformations occur as a series of replacement rules and filters. For many purposes these filters take the form of external calls to `pandoc`_, which is a utility for converting between many different document formats. One downside is that this makes operations that require global coördination (e.g., cross referencing across cells) somewhat challenging to implement as filters inside templates. -Note that all that we've described is happening in memory. +Note that all that we've described is happening in memory. This is crucial in order to ensure that this functionality is available when writing files is more challenging. Nonetheless, the reason for using nbconvert almost always involves producing some kind of output file. We take the in-memory object and write a file appropriate for the output type. -The entirety of heretofore described process can be described as part of an ``Exporter``. -``Exporter``\s often involves ``Preprocessor``\s, ``filters``, ``templates`` and ``Writer``\s. +The entirety of heretofore described process can be described as part of an ``Exporter``. +``Exporter``\s often involves ``Preprocessor``\s, ``filters``, ``templates`` and ``Writer``\s. These classes and functions are described in greater detail below. -Finally, one can apply a ``Postprocessor`` after the writing has occurred. +Finally, one can apply a ``Postprocessor`` after the writing has occurred. For example, it is common when converting to slides to start a webserver and open a browser window with the newly created document (``--to slides --post serve``). Classes @@ -61,7 +61,7 @@ Classes Exporters --------- -The primary class in nbconvert is the `Exporter`. +The primary class in nbconvert is the ``nbconvert.exporters.exporter.Exporter``. Exporters encapsulate the operation of turning a notebook into another format. There is one Exporter for each format supported in nbconvert. The first thing an Exporter does is load a notebook, usually from a file via :mod:`nbformat`. @@ -80,7 +80,7 @@ Once the notebook is loaded, it is preprocessed... Preprocessors ------------- -A `Preprocessor` is an object that transforms the content of the notebook to be exported. +A ``nbconvert.preprocessors.Preprocessor`` is an object that transforms the content of the notebook to be exported. The result of a preprocessor being applied to a notebook is always a notebook. These operations include re-executing the cells, stripping output, removing bundled outputs to separate files, etc. @@ -99,7 +99,7 @@ Once a notebook is preprocessed, it's time to convert the notebook into the dest Templates --------- -Most Exporters in nbconvert are a subclass of `TemplateExporter`, which make use of +Most Exporters in nbconvert are a subclass of ``nbconvert.exporters.templateexporter.TemplateExporter``, which make use of `jinja`_ to render a notebook into the destination format. Nbconvert templates can be selected from the command line with the ``--template`` @@ -151,7 +151,7 @@ Configurable classes. .. seealso:: - :doc:`customizing` - - :ref:`jinja:filters` + - `More on Jinja Filters`_ Once it has passed through the template, an Exporter is done with the notebook, and returns the file data. @@ -180,12 +180,12 @@ Postprocessors -------------- A *Postprocessor* is something that runs after everything is exported and written to the filesystem. -The only postprocessor in nbconvert at this point is the `ServePostProcessor`, +The only postprocessor in nbconvert at this point is the ``nbconvert.postprocessors.serve.ServePostProcessor``, which is used for serving `reveal.js`_ HTML slideshows. .. links: -.. _jinja: http://jinja.pocoo.org/ -.. _filter: http://jinja.pocoo.org/docs/dev/templates/#filters +.. _jinja: https://jinja.palletsprojects.com/en/3.0.x/ +.. _More on Jinja Filters: https://jinja.palletsprojects.com/en/3.0.x/templates/#filters .. _reveal.js: http://lab.hakim.se/reveal-js .. _pandoc: https://pandoc.org/ diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst index 8ae7c303a..a07c98491 100644 --- a/docs/source/changelog.rst +++ b/docs/source/changelog.rst @@ -482,12 +482,12 @@ There were a few new metadata fields which are now respected in nbconvert. ``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. +``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 `_ 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. +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. @@ -660,12 +660,12 @@ Comprehensive notes - new: configurable ``browser`` in ServePostProcessor :ghpull:`618` - new: ``--clear-output`` command line flag to clear output in-place :ghpull:`619` -- new: remove elements based on tags with `TagRemovePreprocessor`. :ghpull:`640`, :ghpull:`643` +- new: remove elements based on tags with ``TagRemovePreprocessor``. :ghpull:`640`, :ghpull:`643` - new: CellExecutionError can now be imported from ``nbconvert.preprocessors`` :ghpull:`656` - new: slides now can enable scrolling and custom transitions :ghpull:`600` - docs: Release instructions for nbviewer-deploy -- docs: improved instructions for handling errors using the `ExecutePreprocessor` :ghpull:`656` +- docs: improved instructions for handling errors using the ``ExecutePreprocessor`` :ghpull:`656` - tests: better height/width metadata testing for images in rst & html :ghpull:`601` :ghpull:`602` - tests: normalise base64 output data to avoid false positives :ghpull:`650` diff --git a/docs/source/execute_api.rst b/docs/source/execute_api.rst index d4fd246d7..f3617add5 100644 --- a/docs/source/execute_api.rst +++ b/docs/source/execute_api.rst @@ -118,7 +118,7 @@ there are no execution errors. But, what if there are errors? Execution until first error ~~~~~~~~~~~~~~~~~~~~~~~~~~~ An error during the notebook execution, by default, will stop the execution -and raise a `CellExecutionError`. Conveniently, the source cell causing +and raise a ``CellExecutionError``. Conveniently, the source cell causing the error and the original error name and message are also printed. After an error, we can still save the notebook as before:: @@ -148,7 +148,7 @@ A useful pattern to execute notebooks while handling errors is the following:: This 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 +``CellExecutionError`` is raised. The message directs the user to the saved notebook for further inspection. Execute and save all errors diff --git a/docs/source/external_exporters.rst b/docs/source/external_exporters.rst index df324ed78..cd18a6ca0 100644 --- a/docs/source/external_exporters.rst +++ b/docs/source/external_exporters.rst @@ -101,7 +101,7 @@ for any ``nbconvert`` exporters you can use either the configuration file syntax ``c.MyExporter.config_option=value`` or the command line flag form ``--MyExporter.config_option=value``. -Writing a custom `Exporter` +Writing a custom ``Exporter`` ============================= Under the hood exporters are python classes that expose a certain interface. diff --git a/nbconvert/exporters/base.py b/nbconvert/exporters/base.py index 25c29aad7..caadcb9c8 100644 --- a/nbconvert/exporters/base.py +++ b/nbconvert/exporters/base.py @@ -42,7 +42,7 @@ def export(exporter, nb, **kw): Parameters ---------- - exporter : `Exporter` class or instance + exporter : ``Exporter`` class or instance Class or instance of the exporter that should be used. If the method initializes its own instance of the class, it is ASSUMED that the class type provided exposes a constructor (``__init__``) with the same diff --git a/nbconvert/exporters/exporter.py b/nbconvert/exporters/exporter.py index 51c1bb87d..1df594043 100644 --- a/nbconvert/exporters/exporter.py +++ b/nbconvert/exporters/exporter.py @@ -203,13 +203,13 @@ def register_preprocessor(self, preprocessor, enabled=False): """ Register a preprocessor. Preprocessors are classes that act upon the notebook before it is - passed into the Jinja templating engine. preprocessors are also + passed into the Jinja templating engine. Preprocessors are also capable of passing additional information to the Jinja templating engine. Parameters ---------- - preprocessor : `Preprocessor` + preprocessor : `nbconvert.preprocessors.Preprocessor` A dotted module name, a type, or an instance enabled : bool Mark the preprocessor as enabled @@ -316,7 +316,7 @@ def _preprocess(self, nb, resources): # to each preprocessor for preprocessor in self._preprocessors: nbc, resc = preprocessor(nbc, resc) - try: + try: nbformat.validate(nbc, relax_add_props=True) except nbformat.ValidationError: self.log.error('Notebook is invalid after preprocessor %s', diff --git a/nbconvert/exporters/webpdf.py b/nbconvert/exporters/webpdf.py index 54cec4971..cec7ae82e 100644 --- a/nbconvert/exporters/webpdf.py +++ b/nbconvert/exporters/webpdf.py @@ -60,7 +60,7 @@ def _template_data_paths_default(self): where JS in your notebook can execute serverside code! Please use with caution. - https://github.com/puppeteer/puppeteer/blob/main@%7B2020-12-14T17:22:24Z%7D/docs/troubleshooting.md#setting-up-chrome-linux-sandbox + ``https://github.com/puppeteer/puppeteer/blob/main@%7B2020-12-14T17:22:24Z%7D/docs/troubleshooting.md#setting-up-chrome-linux-sandbox`` has more information. This is required for webpdf to work inside most container environments. diff --git a/nbconvert/nbconvertapp.py b/nbconvert/nbconvertapp.py index cff462738..578199d26 100755 --- a/nbconvert/nbconvertapp.py +++ b/nbconvert/nbconvertapp.py @@ -274,7 +274,7 @@ def _postprocessor_class_changed(self, change): help="""The export format to be used, either one of the built-in formats {formats} or a dotted object name that represents the import path for an - `Exporter` class""".format(formats=get_export_names()) + ``Exporter`` class""".format(formats=get_export_names()) ).tag(config=True) notebooks = List([], help="""List of notebooks to convert.