Repository navigation
Docfix/improve description - #45
WeatherGod merged 13 commits into
Conversation
Sorry, something went wrong.
…fferences between pyplot and pylab.
…will clarify the matplotlib design better.
…s were added, a table of contents, and improved the aspect ration of the subplot figures.
There was a problem hiding this comment.
Ben, I think this whole general concepts block is confusing and misleading. A much shorter version might work. Maybe on the idea of hierarchy:
Plotting requires action on a range of levels, from the most general at the top (e.g., "contour this 2-D array") to the most specific at the bottom: (e.g., "color this screen pixel red"). The purpose of a plotting package is to assist the user in visualizing data as easily as possible, with all necessary control--that is, by using relatively high-level commands most of the time, but with the ability to access lower levels. In matplotlib, the highest level of the plotting hierarchy is provided via the state-machine environment of the matplotlib.pyplot module. As in MATLAB, simple functions are used to add plot elements (lines, images, text) to the current axes in the current figure. [maybe put your s-m example here] The next level down in the hierarchy is the first level of the object-oriented interface, in which pyplot is used only for a few functions such as figure creation, and the user explicitly keeps track of figures and axes. [maybe your previous example, but without the gca.] For even more control--which is essential for things like embedding matplotlib plotting in GUI applications--the pyplot level may be dropped completely, leaving a purely object-oriented approach.
Something like this might be enough to lead in to the next section; omitting the examples above might then be best, since the next section has examples.
Sorry, something went wrong.
|
I think my "General Concepts" block started off as one thing, but became an explanation of "state-machine environment" which pops up later. I think we could definitely eliminate the second paragraph in "General Concepts". Then, I should fully explain the hierarchy (I want to mesh my explanation with yours), and defer the explanation of the state-machine to last. I also feel that the examples are really important to directly illustrate what the state-machine environment is. While it is incredibly obvious to you and me, to others, a "state-machine environment" might be a very unintuitive phrase that needs a clean example. Note that my examples are demonstrating something slightly different than the examples later on. Mine uses pyplot, and focuses on implicit/explicit creation of objects while the later examples show the difference between pyplot and pylab. |
Sorry, something went wrong.
|
There is really no difference between pyplot and pylab though, right? Pyplot still provides the same "state-machine" interface, but without all the numpy imports that pylab provides. |
Sorry, something went wrong.
|
On 03/14/2011 12:04 PM, darrendale wrote:
|
Sorry, something went wrong.
I don't see how that changed in usage_faq.rst. I could make it more explicit, but I think it would only serve to confuse the reader further because they will wonder what's the point of having the two interfaces. |
Sorry, something went wrong.
|
Let me know if this is better. |
Sorry, something went wrong.
|
On 03/15/2011 05:15 AM, WeatherGod wrote:
Eric |
Sorry, something went wrong.
There was a problem hiding this comment.
That should be "build-dep", not "build_dep"
Sorry, something went wrong.
There was a problem hiding this comment.
Fixed. Thanks for catching that.
Sorry, something went wrong.
|
If there are no more comments on these docs, shall I assume it is good to merge? |
Sorry, something went wrong.
|
On 03/25/2011 03:57 AM, WeatherGod wrote:
Eric |
Sorry, something went wrong.
modifying styles for latest template
My work so far to improve the documentation in various places. This is far from complete and I hope someone else can contribute more improvements.
Of particular focus were grammatical and spelling errors, descriptions of how to use matplotlib (including differences between pylab and pyplot), expanded discussion of the show() command, and improvements to the docs for mplot3d.
I have also worked to eliminate some of the sphinx warning messages, but I have not addressed any of the plot directive errors.