Doc organize axes docs #7176
Doc organize axes docs #7176
Conversation
This: - makes the axes_api page a collection of tables which are grouped reasonably - gives each method it's own web page
|
http://tacaswell.github.io/matplotlib/api/axes_api.html is what it looks like now. |
|
Wow! What an improvement! |
|
|
||
| Axes.grid | ||
|
|
||
| Axes.get_axis_bgcolor |
There was a problem hiding this comment.
Should we keep the documentation of deprecated methods in here?
There was a problem hiding this comment.
The way this is currently working, these are what is triggering the auto-generate sub-pages to be created. If we do not include these here then these methods are not documented at all.
Maybe move all the deprecated methods to 'Deprecated' section at the bottom?
There was a problem hiding this comment.
I think that'd be nice, thought as long as these are clearly documented as deprecated (which they are), I am fine with how it is right now.
| Axes.get_default_bbox_extra_artists | ||
| Axes.get_transformed_clip_path_and_affine | ||
| Axes.has_data | ||
| Axes.hold |
There was a problem hiding this comment.
Maybe this is the time to add a "Future Deprecation Warning" to the docstring in view of #3070
If the first line ends in '::', automsummary generates invalid rst
- remove identical code in YAxis and XAxis, move to Axis - add abstract methods on Axis and Tick to make documenting easier
|
I took a stab at doing the Axis and Tick API as well. http://tacaswell.github.io/matplotlib/api/axis_api.html I think I am going to write a sphinx extension to generate the 'inherited from Artist' sections. Generated the list of methods / attributes via for n in sorted(list(set(dir(maxis.Axis)) - set(dir(matplotlib.artist.Artist)))):
print('Axis.' + n) if n[0] != '_' else None |
There is probably a better way to get this, but this is effective.
Code used to generate this list:
def _recursive_subclasses(cls):
"Return all subclasses (and their subclasses, etc.)."
# Source: http://stackoverflow.com/a/3862957/1221924
return (cls.__subclasses__() +
[g for s in cls.__subclasses__() for g in _recursive_subclasses(s)])
' '.join(sorted(['.'.join((_.__module__, _.__name__)) for _ in _recursive_subclasses(matplotlib.artist.Artist)]))
| =========== | ||
|
|
||
| .. inheritance-diagram:: Tick Ticker XAxis YAxis XTick YTick | ||
| :private-bases: |
There was a problem hiding this comment.
Is there a reason for not having the inheritance diagram always at the top (preferable to me) or always at the bottom.
There was a problem hiding this comment.
Because I thought it went better at the top in Artist and better at the bottom here. The reason for that is that I would expect users to frequently directly use the Axis classes, but not the Tick classes, hence I put the diagram at the bottom. Having now written out this justification, that makes me think that Axis and Tick should get their own pages.
There was a problem hiding this comment.
And I now see this is really at the top so I am not sure what I was remembering...
There was a problem hiding this comment.
I think this could be moved to the bottom for all figures.
Opening a bug #7190.
|
I'll merge this PR in 48hours unless someone has major complaints or updates the PR with new information. |
|
Thank you @tacaswell ! That's a great improvement on our documentation. |
|
Note: those changes should also be added to master. |
|
@tacaswell, I want to say a big Thank-you for this. I am new to using matplotlib, and I was very confused about how it worked and how to use it. Before this update, I had tried to figure out the object oriented side, but I had little success. It is very understandable now. I am teaching a course in which the students use matplotlib, and this documentation improvement is a big help to me in my course. - Thanks. |
No description provided.