matplotlib-devel Mailing List for matplotlib

It's helped by pulling the green towards blue and the red towards yellow,
but they are probably the hardest to distinguish in the set.
Which emphasizes that, while it's good to start with a colorblind-friendly
set of colors, the person making the figure also has the responsibility to
choose how to use those colors carefully so that the categories that are
most important to distinguish aren't colored with red and green.
On Mon, Feb 16, 2015 at 3:32 PM, Eric Firing <ef...@ha...> wrote:
> On 2015年02月16日 1:19 PM, Michael Waskom wrote:
>
>> Here are two palettes that are optimized for colorblindness:
>> http://www.cookbook-r.com/Graphs/Colors_%28ggplot2%29/#
>> a-colorblind-friendly-palette
>>
>>
> Strange--they have both red and green, so I would never have expected them
> to work. The yellow looks too light to work well on a light background,
> especially for projecting slides.
>
> Eric
>

On 2015年02月16日 1:29 PM, Michael Waskom wrote:
> Nathaniel's January 9 message in that thread (can't figure out how to
> link to it in the archives) had a suggestion that I thought was very
> promising, to do something similar to Parula but rotate around the hue
> circle the other direction so that the hues would go blue - purple - red
> - yellow. I don't think we've seen an example of exactly what it would
> look like, but I reckon it would be similar to the middle colormap here
> http://earthobservatory.nasa.gov/blogs/elegantfigures/files/2013/08/three_perceptual_palettes_618.png
> (from the elegant figures block series linked above), which I've always
> found quite attractive.
Certainly it can be considered--but we have to have a real implementation.

On 2015年02月16日 1:19 PM, Michael Waskom wrote:
> Here are two palettes that are optimized for colorblindness:
> http://www.cookbook-r.com/Graphs/Colors_%28ggplot2%29/#a-colorblind-friendly-palette
>
Strange--they have both red and green, so I would never have expected 
them to work. The yellow looks too light to work well on a light 
background, especially for projecting slides.
Eric

On Mon, Feb 16, 2015 at 2:01 PM, Eric Firing <ef...@ha...> wrote:
>
> Here is what I think is the most recent extensive thread:
> http://comments.gmane.org/gmane.comp.python.matplotlib.devel/13122
...
> 1) A greyscale has been proposed; it satisfies several of the criteria
> very well, but misses by omitting hue entirely. It is proposed as a way
> to force users to choose something other than the default; I don't think
> this is a good *competitive* strategy.
>
> 2) YlGnBu or YlGnBu_r seems to me to be a viable candidate. It has the
> great advantage that we already have it. It seems to rate well by most
> of the criteria illustrated via Nathaniel's
> https://github.com/njsmith/pycam02ucs viscm() tool. (Perceptual distance
> is a little jumpy.)
>
> Others?
>
Nathaniel's January 9 message in that thread (can't figure out how to link
to it in the archives) had a suggestion that I thought was very promising,
to do something similar to Parula but rotate around the hue circle the
other direction so that the hues would go blue - purple - red - yellow. I
don't think we've seen an example of exactly what it would look like, but I
reckon it would be similar to the middle colormap here
http://earthobservatory.nasa.gov/blogs/elegantfigures/files/2013/08/three_perceptual_palettes_618.png
(from the elegant figures block series linked above), which I've always
found quite attractive.

On Mon, Feb 16, 2015 at 3:19 PM, Michael Waskom <mw...@st...>
wrote:
> Here are two palettes that are optimized for colorblindness
actually I should say I have no idea if those are optimal, but the
simulations do suggest they work well.

On Mon, Feb 16, 2015 at 3:15 PM, Eric Firing <ef...@ha...> wrote:
> Does anyone have a suggestion for a colorblind-friendly cycle? Maybe
> omit the green and tack a gray on the end? I haven't checked, so I
> don't know if this would work well.
>
Here are two palettes that are optimized for colorblindness:
http://www.cookbook-r.com/Graphs/Colors_%28ggplot2%29/#a-colorblind-friendly-palette
Seaborn has a `colorblind` palette that is somewhere between these colors
and the standard matplotlib/seaborn set. It's intended to be a little
better than deep (which actually isn't too bad in terms of red vs green),
but it's not been extensively tested or optimized.
> It is common to have plots with two curves, and the present blue, green
> pair is not very high-contrast; having the first two colors be blue and
> red would be better, I think.
>
+1

On 2015年02月16日 12:42 PM, Paul Hobson wrote:
> There are several cycles in seaborn. Is it safe to assume that you mean
> the 'deep' palette?
Yes, in the sense that when I wrote the message I was just looking at 
seaborn's tutorial showing the default, which is 'deep'--but I didn't 
know it then.
A good case could be made for "dark"; it has better contrast among all 
the colors. It might be better than "deep" for line plots, especially 
when the lines are thin.
The main point was to get at least one plausible choice on the table.
Does anyone have a suggestion for a colorblind-friendly cycle? Maybe 
omit the green and tack a gray on the end? I haven't checked, so I 
don't know if this would work well.
It is common to have plots with two curves, and the present blue, green 
pair is not very high-contrast; having the first two colors be blue and 
red would be better, I think.
Eric
> On Mon, Feb 16, 2015 at 14:40 Eric Firing <ef...@ha...
> <mailto:ef...@ha...>> wrote:
>
> On 2015年02月16日 12:01 PM, Eric Firing wrote:
>
> >
> > Proposals for the new color cycle for line plots?
>
> Here is a proposal: we simply adopt seaborn's cycle.
>
> Eric

There are several cycles in seaborn. Is it safe to assume that you mean the
'deep' palette?
On Mon, Feb 16, 2015 at 14:40 Eric Firing <ef...@ha...> wrote:
> On 2015年02月16日 12:01 PM, Eric Firing wrote:
>
> >
> > Proposals for the new color cycle for line plots?
>
> Here is a proposal: we simply adopt seaborn's cycle.
>
> Eric
>
>
> ------------------------------------------------------------
> ------------------
> Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server
> from Actuate! Instantly Supercharge Your Business Reports and Dashboards
> with Interactivity, Sharing, Native Excel Exports, App Integration & more
> Get technology previously reserved for billion-dollar corporations, FREE
> http://pubads.g.doubleclick.net/gampad/clk?id=190641631&
> iu=/4140/ostg.clktrk
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>

On 2015年02月16日 12:01 PM, Eric Firing wrote:
>
> Proposals for the new color cycle for line plots?
Here is a proposal: we simply adopt seaborn's cycle.
Eric

For a long time there has been discussion of replacing the matplotlib 
default color map and color cycle, but we still haven't done it. We need 
a clear set of criteria, and a small set of good alternatives, leading 
to a decision, a PR, and a release. Now is the time.
Here is what I think is the most recent extensive thread:
http://comments.gmane.org/gmane.comp.python.matplotlib.devel/13122
Early in that thread Nathaniel Smith proposed the following criteria:
- sequential, not diverging
- perceptually uniform
- still perceptually uniform when converted to greyscale
- variation in hue is good
- colorblind-friendly
- hue ramp should work even without the luminance variation
I added:
- aesthetically pleasing
Probably not all of these can be met perfectly at once, but they seem 
like good goals. The one most likely to be controversial is the first. 
 I propose that we not bother arguing about it, but just accept 
Nathaniel's recommendation.
For actual proposals:
1) A greyscale has been proposed; it satisfies several of the criteria 
very well, but misses by omitting hue entirely. It is proposed as a way 
to force users to choose something other than the default; I don't think 
this is a good *competitive* strategy.
2) YlGnBu or YlGnBu_r seems to me to be a viable candidate. It has the 
great advantage that we already have it. It seems to rate well by most 
of the criteria illustrated via Nathaniel's 
https://github.com/njsmith/pycam02ucs viscm() tool. (Perceptual distance 
is a little jumpy.)
Others?
Proposals for the new color cycle for line plots?
Proposed release strategy:
We will close the 1.4.x line with 1.4.3, in the process of being 
released now.
The next step is the color change release, 2.0, based on 1.4.3, but with 
any additional bug fixes and other reasonably non-risky changes that are 
ready to go.
Any substantial new features will then go in a subsequent point release.
Eric

Hi,
On Mon, Feb 16, 2015 at 1:26 PM, Paul Kuin <np...@gm...> wrote:
> Ah, since it is a proper name it should be capitalised, but it never was. I
> think that it should remain uncapitalised and that you want to propose an
> alternative, like a change in type for the proper name matplotlib. Could be
> typescript, or something else.
I'm guessing the type-setters would object to always using typewriter
(or other special) font for matplotlib, as it would quickly get tiring
on the eye.
Cheers,
Matthew

On 16 February 2015 at 10:53, Nelle Varoquaux <nel...@gm...>
wrote:
> 2. you are used to having sentences start with capital letter, but
> this is mostly cultural. German People capitalize almost all Words in
> a Sentence. It just looks weird too...
>
FWIW, I tried naming a few small projects with all-lowercase names, and I
find it really hard to not capitalise them at the start of a sentence. It
looks far more wrong to me than capitalised Nouns in the middle of a
sentence. You may say this is specific to English, but most documentation
is going to be written in English.
My experience with IPython (aka "iPython") suggests that no-one outside the
project actually cares or even remembers how you capitalise your project
name. ;-)
Thomas

Perhaps this is a bit a of tangent, but what is exactly is the distinction
between the project and the software?
Is it as simple as: software = code and project = code + mailing list +
documentation + managing issues on github?
On Mon, Feb 16, 2015 at 11:04 AM, Matthew Brett <mat...@gm...>
wrote:
> Hi,
>
> On Mon, Feb 16, 2015 at 10:53 AM, Nelle Varoquaux
> <nel...@gm...> wrote:
> >>>>>
> >>>>> IMO, never.
> >>>>
> >>>>
> >>>> Rationale, please?
> >>>
> >>>
> >>> Consistency: it is never capitalized in matplotlib's documentation.
> >>
> >>
> >> True, and a valid point--but we could easily change that. Wouldn't it
> make
> >> it bit more readable if sentences always started with a capital letter?
> >> Starting with lower case just looks wrong and artificial.
> >
> > I'm going to give two bad reasons to keep it this way:
> > 1. backward compatibility :p
> > 2. you are used to having sentences start with capital letter, but
> > this is mostly cultural. German People capitalize almost all Words in
> > a Sentence. It just looks weird too... (There is the other extreme:
> > people who don't seem to know where the shift button on their keyboard
> > is when writing an email.)
> >
> > I'm actually fine with changing it, but I think we should try as much
> > as possible to be consistent.
>
> I suppose everyone would agree that <pre>matplotlib</pre> should never
> be capitalized. I guess also that your (Ben's) typsetters will not
> often be using <pre></pre> formatted matplotlib. In that case I would
> say Matplotlib is a English proper noun and standard capitalization
> rules apply. It would probably be confusing to try and distinguish
> between the project and the software with capitalization.
>
> Does it matter that the book and the mpl documentation have a
> different convention?
>
> Cheers,
>
> Matthew
>
>
> ------------------------------------------------------------------------------
> Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server
> from Actuate! Instantly Supercharge Your Business Reports and Dashboards
> with Interactivity, Sharing, Native Excel Exports, App Integration & more
> Get technology previously reserved for billion-dollar corporations, FREE
>
> http://pubads.g.doubleclick.net/gampad/clk?id=190641631&iu=/4140/ostg.clktrk
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>

Hi,
On Mon, Feb 16, 2015 at 10:53 AM, Nelle Varoquaux
<nel...@gm...> wrote:
>>>>>
>>>>> IMO, never.
>>>>
>>>>
>>>> Rationale, please?
>>>
>>>
>>> Consistency: it is never capitalized in matplotlib's documentation.
>>
>>
>> True, and a valid point--but we could easily change that. Wouldn't it make
>> it bit more readable if sentences always started with a capital letter?
>> Starting with lower case just looks wrong and artificial.
>
> I'm going to give two bad reasons to keep it this way:
> 1. backward compatibility :p
> 2. you are used to having sentences start with capital letter, but
> this is mostly cultural. German People capitalize almost all Words in
> a Sentence. It just looks weird too... (There is the other extreme:
> people who don't seem to know where the shift button on their keyboard
> is when writing an email.)
>
> I'm actually fine with changing it, but I think we should try as much
> as possible to be consistent.
I suppose everyone would agree that <pre>matplotlib</pre> should never
be capitalized. I guess also that your (Ben's) typsetters will not
often be using <pre></pre> formatted matplotlib. In that case I would
say Matplotlib is a English proper noun and standard capitalization
rules apply. It would probably be confusing to try and distinguish
between the project and the software with capitalization.
Does it matter that the book and the mpl documentation have a
different convention?
Cheers,
Matthew

>>>>
>>>> IMO, never.
>>>
>>>
>>> Rationale, please?
>>
>>
>> Consistency: it is never capitalized in matplotlib's documentation.
>
>
> True, and a valid point--but we could easily change that. Wouldn't it make
> it bit more readable if sentences always started with a capital letter?
> Starting with lower case just looks wrong and artificial.
I'm going to give two bad reasons to keep it this way:
1. backward compatibility :p
2. you are used to having sentences start with capital letter, but
this is mostly cultural. German People capitalize almost all Words in
a Sentence. It just looks weird too... (There is the other extreme:
people who don't seem to know where the shift button on their keyboard
is when writing an email.)
I'm actually fine with changing it, but I think we should try as much
as possible to be consistent.
Nele
> Eric
>
>

On Feb 16, 2015 10:35 AM, "Eric Firing" <ef...@ha...> wrote:
>
> On 2015年02月16日 8:16 AM, Benjamin Root wrote:
> > I am in the final rounds of edits for my book and a question has come up
> > between me and the editors. When should the matplotlib be capitalized?
> >
> > 1) never
> > 2) mostly never (even in the beginning of a sentence), except when used
> > in a title
> > 3) usually never, except at the beginning of a sentence and in titles
> > 4) capitalize when referring to the project, not capitalized when
> > referring to the package
> > 5) usually capitalize like a proper noun except in code examples
> >
> > Thoughts?
> > Ben Root
>
> Do numpy and scipy have a consistent policy that could be used as a
> model?
Not that I'm aware of. I tend to write "numpy" in prose (somewhere in the
1-3 range in Ben's terminology) because that's what I write in code. But as
I recently discovered, when writing for a general audience (e.g., "people
reading your job application") it is crucial to write NumPy so that it
doesn't look like it's pronounced nump-ee. :-)
Matplotlib cleverly avoids that particular problem through its surfeit of
stops, but if we want a general cross-project rule then it might be a hint.
-n

On 2015年02月16日 8:38 AM, Nelle Varoquaux wrote:
> On 16 February 2015 at 19:36, Eric Firing <ef...@ha...> wrote:
>> On 2015年02月16日 8:23 AM, Nelle Varoquaux wrote:
>>> IMO, never.
>>
>> Rationale, please?
>
> Consistency: it is never capitalized in matplotlib's documentation.
True, and a valid point--but we could easily change that. Wouldn't it 
make it bit more readable if sentences always started with a capital 
letter? Starting with lower case just looks wrong and artificial.
Eric

On 16 February 2015 at 19:36, Eric Firing <ef...@ha...> wrote:
> On 2015年02月16日 8:23 AM, Nelle Varoquaux wrote:
>> IMO, never.
>
> Rationale, please?
Consistency: it is never capitalized in matplotlib's documentation.
>
> Eric
>
> ------------------------------------------------------------------------------
> Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server
> from Actuate! Instantly Supercharge Your Business Reports and Dashboards
> with Interactivity, Sharing, Native Excel Exports, App Integration & more
> Get technology previously reserved for billion-dollar corporations, FREE
> http://pubads.g.doubleclick.net/gampad/clk?id=190641631&iu=/4140/ostg.clktrk
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel

On 2015年02月16日 8:23 AM, Nelle Varoquaux wrote:
> IMO, never.
Rationale, please?
Eric

On 2015年02月16日 8:16 AM, Benjamin Root wrote:
> I am in the final rounds of edits for my book and a question has come up
> between me and the editors. When should the matplotlib be capitalized?
>
> 1) never
> 2) mostly never (even in the beginning of a sentence), except when used
> in a title
> 3) usually never, except at the beginning of a sentence and in titles
> 4) capitalize when referring to the project, not capitalized when
> referring to the package
> 5) usually capitalize like a proper noun except in code examples
>
> Thoughts?
> Ben Root
Do numpy and scipy have a consistent policy that could be used as a 
model? Or newer related packages? I think the trend is toward more use 
of capitalization to make a project name stand out.
Based on our web front page, it looks like our present policy is either 
1 or 2. Failing to capitalize at the beginning of a sentence is 
awkward, though, so I would be inclined to change this and at least move 
to 3.
The SciPy front page awards us a capitalization--only pandas is all 
lower case there.
(In retrospect, the "mat" part of the matplotlib name is an unfortunate 
legacy. If we were starting afresh we might use something like "PyPlot" 
for the project and pyplot for the package as a whole.)
Eric

IMO, never.
On 16 February 2015 at 19:16, Benjamin Root <ben...@ou...> wrote:
> I am in the final rounds of edits for my book and a question has come up
> between me and the editors. When should the matplotlib be capitalized?
>
> 1) never
> 2) mostly never (even in the beginning of a sentence), except when used in a
> title
> 3) usually never, except at the beginning of a sentence and in titles
> 4) capitalize when referring to the project, not capitalized when referring
> to the package
> 5) usually capitalize like a proper noun except in code examples
>
> Thoughts?
> Ben Root
>
> ------------------------------------------------------------------------------
> Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server
> from Actuate! Instantly Supercharge Your Business Reports and Dashboards
> with Interactivity, Sharing, Native Excel Exports, App Integration & more
> Get technology previously reserved for billion-dollar corporations, FREE
> http://pubads.g.doubleclick.net/gampad/clk?id=190641631&iu=/4140/ostg.clktrk
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>

I am in the final rounds of edits for my book and a question has come up
between me and the editors. When should the matplotlib be capitalized?
1) never
2) mostly never (even in the beginning of a sentence), except when used in
a title
3) usually never, except at the beginning of a sentence and in titles
4) capitalize when referring to the project, not capitalized when referring
to the package
5) usually capitalize like a proper noun except in code examples
Thoughts?
Ben Root

At risk of sounding defensive, all of the core developers are working mpl
on a mostly volunteer basis and only have so much bandwidth. This leads to
both thing falling through the cracks (we have close to 100 open PRs, that
is _way_ too many) and major re-factors (which every one agrees should be
done) not being done.
I fully agree the docs are less than ideal. Some of what you suggest is
already on the radar (giving each plotting function it's own page) and a
complete overhaul of the webpage is (very slowly) in the works.
http://matplotlib.org/api/pyplot_summary.html covers some of the use-case
of the table of contents.
The reason that plotting methods appear in both `Axes` and in `pyplot` is
due to the layered design of mpl. The actual plotting logic is implemented
as methods on the Axes object and the pyplot layer provides a MATLAB-like
state machine to make plotting convenient. The fact that you have the same
functions in both places is a feature, not a bug ;). We don't use
decorators for `pyplot.py` because that code pre-dates fully functional
decorators.
This part of the design, the plotting logic being _methods_ on the `Axes`
object, is why the `Axes` class is so large and I do not think can be
broken up in any sensible way (at the code level) short of abandoning it
all together and moving to modules of functions with signatures like
`fun(ax, data, style)`. This has been discussed, but it is a HUGE change
to the architecture of the library and we are (rightly) moving slowly on
it. MPL is a widely used mature library which means one of the most
important things we have to do is not break existing user code.
Providing human curation to the docs (a-la numpy) would be great, the main
problem is time. The core-devs (who seem to enjoy very drudgery) are
already over whelmed, 'update the docs' is not really an exciting thing
that new contributors will jump on, and fixing the docs does require a good
deal of familiarity with the library (so you know where the docs are
wrong/misleading/missing!).
@Fabio That bit of the already seems pretty modular, but I am not super
familiar with it. What would you change?
If anyone wants to help with MEP10 that would be great!
Tom
On Mon Feb 16 2015 at 7:02:13 AM Fabio Zanini <fab...@tu...>
wrote:
> Dear Sebastian,
>
> I agree with your impression. I made a pull request for some axis
> functionality (logit scales) and the PR got lost. I am convinced that:
>
> 1. working on things like axes, ticker, scales, locators would be a lot
> easier with a little refactoring of the code
>
> 2. with a more modular codebase, my PR would be accepted by now, instead
> of living in limbo waiting to be forgotten.
>
> So I am in general in favour of your proposal.
>
> See also: https://github.com/matplotlib/matplotlib/pull/3753
>
> Cheers,
> Fabio
>
> PS: if Thomas or anybody else is still willing to accept my PR itself,
> I'd be in favour too. But please do not make me rebase another 3 times
> before that ;-)
>
> On 02/16/2015 11:42 AM, Sebastian Werhausen wrote:
> > I'm a newcomer to the MPL code, and getting an overview is not easy.
> > Especially the API part of the documentation [1] has a lot of room for
> > improvement. The functionality of the MPL sources seems to be
> > scattered quite loosely among the sources and their structure is
> > directly mirrored in the doc. Some observations:
> >
> > 1. Many functions like quiver() or bar() are in multiple places
> > (pyplot and axes)
> > 2. Some entries (like axes) are enormous, making them very hard to use
> > to get an overview
> > 3. The API start page is just a lose list of classes, without
> > indication what's inside
> >
> > Ideally I feel like the code itself should be organized in smaller
> > chunks, but that's probably unrealistic. A quick improvement for 2.
> > could be to add a "table of contents" at the top of every class
> > documentation. For axes, that could work like [2] and look like [3].
> > Thoughts? I wanted to test the waters before making pull requests.
> >
> > Another way could be to organize the documentation not by classes, but
> > by functionality. The Numpy docs [4] seem much more usable in that
> > regard. That'll be less automatic of course but could help with
> > observation 3.
> >
> > I've also found the Mep10 [5] on the Wiki with many good ideas, but
> > not sure if that lead somewhere.
> >
> > Sebastian
> >
> >
> > [1] http://matplotlib.org/api/index.html
> > [2] https://github.com/s9w/matplotlib/commit/
> 053179c9491637609775e21855f21e977580a0a1
> > [3] http://i.imgur.com/d1uTjfS.png
> > [4] http://docs.scipy.org/doc/numpy/reference/
> > [5] https://github.com/matplotlib/matplotlib/wiki/Mep10
> >
> > ------------------------------------------------------------
> ------------------
> > Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server
> > from Actuate! Instantly Supercharge Your Business Reports and Dashboards
> > with Interactivity, Sharing, Native Excel Exports, App Integration & more
> > Get technology previously reserved for billion-dollar corporations, FREE
> > http://pubads.g.doubleclick.net/gampad/clk?id=190641631&
> iu=/4140/ostg.clktrk
> > _______________________________________________
> > Matplotlib-devel mailing list
> > Mat...@li...
> > https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
> >
>
> ------------------------------------------------------------
> ------------------
> Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server
> from Actuate! Instantly Supercharge Your Business Reports and Dashboards
> with Interactivity, Sharing, Native Excel Exports, App Integration & more
> Get technology previously reserved for billion-dollar corporations, FREE
> http://pubads.g.doubleclick.net/gampad/clk?id=190641631&
> iu=/4140/ostg.clktrk_______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
>

Dear Sebastian,
I agree with your impression. I made a pull request for some axis
functionality (logit scales) and the PR got lost. I am convinced that:
1. working on things like axes, ticker, scales, locators would be a lot
easier with a little refactoring of the code
2. with a more modular codebase, my PR would be accepted by now, instead
of living in limbo waiting to be forgotten.
So I am in general in favour of your proposal.
See also: https://github.com/matplotlib/matplotlib/pull/3753
Cheers,
Fabio
PS: if Thomas or anybody else is still willing to accept my PR itself,
I'd be in favour too. But please do not make me rebase another 3 times
before that ;-)
On 02/16/2015 11:42 AM, Sebastian Werhausen wrote:
> I'm a newcomer to the MPL code, and getting an overview is not easy.
> Especially the API part of the documentation [1] has a lot of room for
> improvement. The functionality of the MPL sources seems to be
> scattered quite loosely among the sources and their structure is
> directly mirrored in the doc. Some observations:
> 
> 1. Many functions like quiver() or bar() are in multiple places
> (pyplot and axes)
> 2. Some entries (like axes) are enormous, making them very hard to use
> to get an overview
> 3. The API start page is just a lose list of classes, without
> indication what's inside
> 
> Ideally I feel like the code itself should be organized in smaller
> chunks, but that's probably unrealistic. A quick improvement for 2.
> could be to add a "table of contents" at the top of every class
> documentation. For axes, that could work like [2] and look like [3].
> Thoughts? I wanted to test the waters before making pull requests.
> 
> Another way could be to organize the documentation not by classes, but
> by functionality. The Numpy docs [4] seem much more usable in that
> regard. That'll be less automatic of course but could help with
> observation 3.
> 
> I've also found the Mep10 [5] on the Wiki with many good ideas, but
> not sure if that lead somewhere.
> 
> Sebastian
> 
> 
> [1] http://matplotlib.org/api/index.html
> [2] https://github.com/s9w/matplotlib/commit/053179c9491637609775e21855f21e977580a0a1
> [3] http://i.imgur.com/d1uTjfS.png
> [4] http://docs.scipy.org/doc/numpy/reference/
> [5] https://github.com/matplotlib/matplotlib/wiki/Mep10
> 
> ------------------------------------------------------------------------------
> Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server
> from Actuate! Instantly Supercharge Your Business Reports and Dashboards
> with Interactivity, Sharing, Native Excel Exports, App Integration & more
> Get technology previously reserved for billion-dollar corporations, FREE
> http://pubads.g.doubleclick.net/gampad/clk?id=190641631&iu=/4140/ostg.clktrk
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
> 

I'm a newcomer to the MPL code, and getting an overview is not easy.
Especially the API part of the documentation [1] has a lot of room for
improvement. The functionality of the MPL sources seems to be
scattered quite loosely among the sources and their structure is
directly mirrored in the doc. Some observations:
1. Many functions like quiver() or bar() are in multiple places
(pyplot and axes)
2. Some entries (like axes) are enormous, making them very hard to use
to get an overview
3. The API start page is just a lose list of classes, without
indication what's inside
Ideally I feel like the code itself should be organized in smaller
chunks, but that's probably unrealistic. A quick improvement for 2.
could be to add a "table of contents" at the top of every class
documentation. For axes, that could work like [2] and look like [3].
Thoughts? I wanted to test the waters before making pull requests.
Another way could be to organize the documentation not by classes, but
by functionality. The Numpy docs [4] seem much more usable in that
regard. That'll be less automatic of course but could help with
observation 3.
I've also found the Mep10 [5] on the Wiki with many good ideas, but
not sure if that lead somewhere.
Sebastian
[1] http://matplotlib.org/api/index.html
[2] https://github.com/s9w/matplotlib/commit/053179c9491637609775e21855f21e977580a0a1
[3] http://i.imgur.com/d1uTjfS.png
[4] http://docs.scipy.org/doc/numpy/reference/
[5] https://github.com/matplotlib/matplotlib/wiki/Mep10