Deprecate :encoding: option to .. plot::, which has no effect since 2011

(Its value is not read anywhere in the implementation since a205f54.)

Author: anntzer

doc/api/next_api_changes/deprecations/20540-AL.rst

@@ -0,0 +1,3 @@
+``:encoding:`` option to ``.. plot`` directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This option has had no effect since Matplotlib 1.3.1, and is now deprecated.

lib/matplotlib/sphinxext/plot_directive.py

@@ -194,6 +194,11 @@ def _option_format(arg):
     return directives.choice(arg, ('python', 'doctest'))
 
 
+def _deprecated_option_encoding(arg):
+    _api.warn_deprecated("3.5", "encoding", obj_type="option")
+    return directives.encoding(arg)
+
+
 def mark_plot_labels(app, document):
     """
     To make plots referenceable, we need to move the reference from the
@@ -242,7 +247,7 @@ class PlotDirective(Directive):
         'format': _option_format,
         'context': _option_context,
         'nofigs': directives.flag,
-        'encoding': directives.encoding,
+        'encoding': _deprecated_option_encoding,
         'caption': directives.unchanged,
         }