Allow ACCEPTS as ReST comment in docstrings

timhoffm · timhoffm · commit 3cf8bdf69dd9 · 2018-01-22T23:56:47.000+01:00
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -478,6 +478,22 @@ acceptable values in the docs; it can also be displayed using, e.g.,
 ``plt.setp(Line2D)`` (all properties) or ``plt.setp(Line2D, 'linestyle')``
 (just one property).
 
+There are cases in which the ACCEPTS string is not useful in the
+generated Sphinx documentation, e.g. if the valid parameters are already
+defined in the numpydoc parameter list. You can hide the ACCEPTS string from
+Sphinx by making it a ReST comment (i.e. use ``.. ACCEPTS:``):
+
+.. code-block:: python
+
+   def set_linestyle(self, linestyle):
+       """
+       An ACCEPTS string invisible to Sphinx.
+
+       .. ACCEPTS: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' | ' ' | '' ]
+       """
+
+
+
 Keyword arguments
 -----------------
 
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -1133,15 +1133,15 @@ def get_aliases(self):
         return aliases
 
     _get_valid_values_regex = re.compile(
-        r"\n\s*ACCEPTS:\s*((?:.|\n)*?)(?:$|(?:\n\n))"
+        r"\n\s*(?:\.\.\s+)?ACCEPTS:\s*((?:.|\n)*?)(?:$|(?:\n\n))"
     )
 
     def get_valid_values(self, attr):
         """
         Get the legal arguments for the setter associated with *attr*.
 
         This is done by querying the docstring of the function *set_attr*
-        for a line that begins with ACCEPTS:
+        for a line that begins with "ACCEPTS" or ".. ACCEPTS":
 
         e.g., for a line linestyle, return
         "[ ``'-'`` | ``'--'`` | ``'-.'`` | ``':'`` | ``'steps'`` | ``'None'``
diff --git a/lib/matplotlib/tests/test_artist.py b/lib/matplotlib/tests/test_artist.py
@@ -6,6 +6,8 @@
 
 import numpy as np
 
+import pytest
+
 import matplotlib.pyplot as plt
 import matplotlib.patches as mpatches
 import matplotlib.lines as mlines
@@ -255,3 +257,26 @@ def test_None_zorder():
     assert ln.get_zorder() == 123456
     ln.set_zorder(None)
     assert ln.get_zorder() == mlines.Line2D.zorder
+
+
+@pytest.mark.parametrize('accept_clause, expected', [
+    ('', 'unknown'),
+    ("ACCEPTS: [ '-' | '--' | '-.' ]", "[ '-' | '--' | '-.' ] "),
+    ('ACCEPTS: Some description.', 'Some description. '),
+    ('.. ACCEPTS: Some description.', 'Some description. '),
+])
+def test_artist_inspector_get_valid_values(accept_clause, expected):
+    class TestArtist(martist.Artist):
+        def set_f(self):
+            pass
+
+    func = TestArtist.set_f
+    if hasattr(func, '__func__'):
+        func = func.__func__  # python 2 must write via __func__.__doc__
+    func.__doc__ = """
+    Some text.
+
+    %s
+    """ % accept_clause
+    valid_values = martist.ArtistInspector(TestArtist).get_valid_values('f')
+    assert valid_values == expected
