Working with the documentation this past week has me a little frustrated with the state of it. Enough to write a MEP. https://github.com/matplotlib/matplotlib/wiki/Mep10 In particular, it would be nice to compile a list of concerns about the docstrings and documentation layout so that we can address as much as possible in a single pass. Also, let me know if there are any relevant PRs and Issues. In particular, I think PR #1032, as it is a large structural reorganization, my dovetail well with the proposed reorganization of the docs. Mike
Michael Droettboom <mdroe@...> writes: > > > > Working with the documentation this past week has me a little > frustrated with the state of it. Enough to write a MEP. https://github.com/matplotlib/matplotlib/wiki/Mep10 > In particular, it would be nice to compile a list of concerns about > the docstrings and documentation layout so that we can address as > much as possible in a single pass. Also, let me know if there are > any relevant PRs and Issues. > In particular, I think PR #1032, as it is a large structural > reorganization, my dovetail well with the proposed reorganization of > the docs. > Mike The proposal looks great. I would like to comment on one issue that it touches, and which I found very uncomfortable to work with as a newcomer. I think that matplotlib style of using *args and **kwargs for delegation of arguments is a rather bad practice, which is hard to solve by just updating documentation. It breaks many rules of pep 20: it is implicit, since it is not allowing introspection, it is nested, since it always involves nested calls, it allows for alternative ways to do things, and I also don't think it's anyhow beautiful. Most of the things passed with *args, **kwargs can be done with an added function call, like: points = ax.scatter(data) points.update(*args, **kwargs) What would be the disadvantage of abolishing this practice? Anton
On 08/26/2012 05:33 AM, Anton Akhmerov wrote: > Michael Droettboom <mdroe@...> writes: > >> >> >> Working with the documentation this past week has me a little >> frustrated with the state of it. Enough to write a MEP. > https://github.com/matplotlib/matplotlib/wiki/Mep10 >> In particular, it would be nice to compile a list of concerns about >> the docstrings and documentation layout so that we can address as >> much as possible in a single pass. Also, let me know if there are >> any relevant PRs and Issues. >> In particular, I think PR #1032, as it is a large structural >> reorganization, my dovetail well with the proposed reorganization of >> the docs. >> Mike > The proposal looks great. I would like to comment on one issue that it touches, > and which I found very uncomfortable to work with as a newcomer. I think that > matplotlib style of using *args and **kwargs for delegation of arguments is a > rather bad practice, which is hard to solve by just updating documentation. It > breaks many rules of pep 20: it is implicit, since it is not allowing > introspection, it is nested, since it always involves nested calls, it allows > for alternative ways to do things, and I also don't think it's anyhow beautiful. > Most of the things passed with *args, **kwargs can be done with an added > function call, like: > > points = ax.scatter(data) > points.update(*args, **kwargs) > > What would be the disadvantage of abolishing this practice? > I understand the comments about the difficulty of introspection. The reason it works the way it does is so that additional parameters can be added to the artist layer without needing to update every single plotting function. A real world example of this is when hatching was added -- that feature only had to be added in one place and most artists were able to use it. In that sense, I think this approach is very beautiful in terms of code maintainability and extensibility. I'm willing to consider this if there's a better suggestion, but I think pushing what is currently a single function call for the user in to two is not going to fly. An alternative might be to have "style" objects that are passed to the plotting functions, and these style objects could grow new features over time. But that's going to break a lot of backward compatibility, of course. Mike
On 26 August 2012 18:19, Michael Droettboom <md...@st...> wrote: > I understand the comments about the difficulty of introspection. The > reason it works the way it does is so that additional parameters can be > added to the artist layer without needing to update every single > plotting function. A real world example of this is when hatching was > added -- that feature only had to be added in one place and most artists > were able to use it. In that sense, I think this approach is very > beautiful in terms of code maintainability and extensibility. I'm jumping into this conversation a bit late, but from Python 3.3 it will be possible to set a __signature__ attribute on a function, using a Signature object which can be programmatically generated. So it should be possible, with a bit of legwork, to introspect pass-through parameters without having to manually declare them at the highest level. The details are here: http://www.python.org/dev/peps/pep-0362/ Thanks, Thomas
Michael Droettboom <mdroe@...> writes: > > On 08/26/2012 05:33 AM, Anton Akhmerov wrote: > > Michael Droettboom <mdroe@...> writes: > > > >> > >> > >> Working with the documentation this past week has me a little > >> frustrated with the state of it. Enough to write a MEP. > > https://github.com/matplotlib/matplotlib/wiki/Mep10 > >> In particular, it would be nice to compile a list of concerns about > >> the docstrings and documentation layout so that we can address as > >> much as possible in a single pass. Also, let me know if there are > >> any relevant PRs and Issues. > >> In particular, I think PR #1032, as it is a large structural > >> reorganization, my dovetail well with the proposed reorganization of > >> the docs. > >> Mike > > The proposal looks great. I would like to comment on one issue that it touches, > > and which I found very uncomfortable to work with as a newcomer. I think that > > matplotlib style of using *args and **kwargs for delegation of arguments is a > > rather bad practice, which is hard to solve by just updating documentation. It > > breaks many rules of pep 20: it is implicit, since it is not allowing > > introspection, it is nested, since it always involves nested calls, it allows > > for alternative ways to do things, and I also don't think it's anyhow beautiful. > > Most of the things passed with *args, **kwargs can be done with an added > > function call, like: > > > > points = ax.scatter(data) > > points.update(*args, **kwargs) > > > > What would be the disadvantage of abolishing this practice? > > > I understand the comments about the difficulty of introspection. The > reason it works the way it does is so that additional parameters can be > added to the artist layer without needing to update every single > plotting function. A real world example of this is when hatching was > added -- that feature only had to be added in one place and most artists > were able to use it. In that sense, I think this approach is very > beautiful in terms of code maintainability and extensibility. First of all, to be clear, I am not trying to be negative about the current situation, I rather search for ways to improve on it. I also realize that any changes like this would be very serious and require a lot of thinking and of course work. Let me first point some drawbacks of the current kwargs usage before discussing the solution. Let me know if you agree. 1. Currenly the aims of extensibility and maintainability are not completely reached, as seen from this part of Axes.scatter docstring: Optional kwargs control the :class:`~matplotlib.collections.Collection` properties; in particular: *edgecolors*: The string 'none' to plot faces with no outlines *facecolors*: The string 'none' to plot unfilled outlines So the explicit descriptions of useful **kwargs are provided. If a new useful property of collections appears, it stays unknown. 2. Yet another problem that **kwargs cause is that it is sometimes completely unclear where an argument ends up. `Axes` methods have a reasonably well- documented kwargs, while, e.g. axis module often fails to mention what happens to kwargs. Another example of misuse is figure.add_axes, where the docstring declares: """...kwargs are legal Axes kwargs plus projection which sets the projection type of the axes. (For backward compatibility, polar=True may also be provided, which is equivalent to projection='polar'). Valid values for projection are: [‘aitoff’, ‘hammer’, ‘lambert’, ‘mollweide’, ‘polar’, ‘rectilinear’]. Some of these projections support additional kwargs, which may be provided to add_axes().""" Despite this is an extensible interface, I still wouldn't call it user-friendly; kwargs are passed to at least two places: Axes and projection. 3. About the hatching: I think this is solved in a rather elegant fashion with symbols for scatter plot: the interpretation of the format is deferred to `mmarkers.MarkerStyle(marker)`. This means that `marker` is in fact already effectively a style object, corresponding to the style object format that you suggested. One can also easily refer to the MarkerStyle docstring in order to make the description complete. 4. The idea behind kwargs, if I understand it correctly, is to let high-level functions, such as all the plot functions handle low-level objects in full generality. This aim cannot be achieved anyway, because high-level functions often generate more than one low-level object. This is why something like this: axis.label.set_text(r"$\theta = 60^{\circ}$") Is still provided as a separate command, and cannot be done via kwargs to scatter. So the user already doesn't have a situation where a single function call is sufficient. --------------------- These altogether seem serious enough to consider changing the behavior in one or another way. They are often also directly related to documentation quality. Best, Anton
On 5 September 2012 00:32, Michael Droettboom <md...@st...> wrote: > I wonder if there's any possibility of using that on earlier versions (I > suspect not). Not easily, I think. You'd have to get introspection tools like IPython to separately check for a __signature__ attribute, and I suspect we'd feel that the added complexity outweighs the benefits. Thomas