Fix docstring issue and a broken link

.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

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`.
 

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

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/

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 <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.
+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`

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

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.

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

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',

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.

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.