Write data parameter docs as regular parameter not as note #19859
Conversation
ee8f655 to
154a139
Compare
91a27b2 to
50e52e7
Compare
There was a problem hiding this comment.
@tacaswell and I were looking at this earlier, and realized that a couple of the asserts in tests with replace_names were wrong. That text is there, but the regex is wrong.
|
I'm not completely sure whether this belongs in 3.4.2; I'll let you know after docs have built. |
Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>
|
I'm fine with moving to 3.5 if this would hold up the 3.4.2 release. |
|
If |
I don't have a strong opinion on this, but it's fine by me. One can argue this on a similar level as further Artist properties, reatively generic and not related to the primary semantic of the method. |
|
Sorry for being dense - where is this change in the built docs? I can't tell from the description. |
|
It's removing the note and instead adding a regular parameter: This change applies to all |
|
I see, I looked at |
TL;DR
Full commentThere are three parts: The docstringWe could make that explicit, but then might want to add a check that the mentioned parameters match with the given An in-between way would be to so that we explicitly specify the position but still auto-generate the content. The keyword
|
|
Thinking of it, I'd go for |
Replaces matplotlib#19859. This approach uses an explicit template ``` data : indexable object, optional # data_parameter_message ``` in the docstring and does not try to guess a reasonable insertion position based on the docstring content. This is much simpler.
Replaces matplotlib#19859. This approach uses an explicit template ``` data : indexable object, optional # data_parameter_message ``` in the docstring and does not try to guess a reasonable insertion position based on the docstring content. This is much simpler.
Replaces matplotlib#19859. This approach uses an explicit template ``` data : indexable object, optional # data_parameter_message ``` in the docstring and does not try to guess a reasonable insertion position based on the docstring content. This is much simpler.
|
Closing in favor of #20291. |
Replaces matplotlib#19859. This approach uses an explicit template ``` data : indexable object, optional # data_parameter_message ``` in the docstring and does not try to guess a reasonable insertion position based on the docstring content. This is much simpler.
Replaces matplotlib#19859. This approach uses an explicit template ``` data : indexable object, optional # DATA_PARAMETER_PLACEHOLDER ``` in the docstring and does not try to guess a reasonable insertion position based on the docstring content. This is much simpler.
Replaces matplotlib#19859. This approach uses an explicit template ``` data : indexable object, optional DATA_PARAMETER_PLACEHOLDER ``` in the docstring and does not try to guess a reasonable insertion position based on the docstring content. This is much simpler.
Replaces matplotlib#19859. This approach uses an explicit template ``` data : indexable object, optional DATA_PARAMETER_PLACEHOLDER ``` in the docstring and does not try to guess a reasonable insertion position based on the docstring content. This is much simpler.
PR Summary
It's cleaner to document this as a normal parameter rather than using a note "The function can take an additional parameter data ...".
The docs is inserted before
**kwargsdocs, or if they do not exist as the last entry inParameters(Which is the case only for a handful of methods.