Tidy up the matplotlib.__init__ documentation.

[pelson]

The matplotlib namespace is really cluttered. Many of the functions here could be static methods or instance methods of the RcParams dictionary class.

I don't want to hold up this PR, but if there is appetite to break backwards compatibility, I'd be willing to tidy it up in a follow-on PR.

[mdboom]

Looks fine to me. I worry about keeping the manual list in matplotlib_configuration_api.rst up-to-date, but as you say, the only way to really fix that is to remove some things from __init__.py. Maybe we schedule that for post 1.3?

[pelson]

I worry about keeping the manual list in matplotlib_configuration_api.rst up-to-date

I empathise with that, but at the end of the day, if somebody adds new functionality to the matplotlib/__init__.py you would expect them to check that what they are adding is documented (as you would expect the reviewer to do also). So personally I'm comfortable with enumerating all of the necessary items in this special case.

Maybe we schedule that for post 1.3?

Hmmm. We could start the deprecation process for v1.3 potentially, and then have them removed in v1.4?

[efiring]

Just a style opinion, not a demand for change: I much prefer the original; the use of the bare underscore makes this sort of thing less readable and slightly ugly to my eye. In the case of the path.split(), an alternative is to index it with [-1].

[pelson]

Ok. Thanks @efiring. I only did this because my editor was shouting at me that dirs was unused - the underscores use is not mentioned in PEP8 (though there is an interesting question on http://stackoverflow.com/questions/11486148/unused-variable-naming-in-python).

[NelleV]

I prefer the use of underscores: it makes explicit that those variable are not used in this file, which is a convention in python and some other languages (perl?). IMO, we should stick to convention as much as possible.

Also, that makes pyflakes not happy.

[efiring]

@pelson, I agree with your original comment about the clutter in init.py. The API is a mess.