[Matplotlib-devel] Documentation

[Matt Arcidy]

Just for fun, I made graphs (too big to send, hosted here:
http://arcidy.com) from the backref information.  Functions used in
examples/tutorials are blue,  examples/tutorials are green.  Red edges
are from functions used in more than 10 tutorials to any tutorial that
uses the function.
- "full.png" has everything
- "filtered.png" as the top 10 most used functions removed.  e.g.
usual suspects like pyplot.plot()
They are big and I have residential internet, so might need a small
bit of patience.

Curious if it inspires ideas for analysis.  Longest path?  shortest
path?  what would these even mean?  I'm working on clustering
functions by module, or other groupings.
If you have ideas to analyze it, or you want any code or other format
(e.g. dot) please let me know.  This is all built off the backrefs
from the gallery, so thank you very much for that.  There's structure
so i just need to keep digging.

As an example, I noted there are separate "pyplot.subplot" (<- no 's')
and "pyplot.subplots" tutorials.  Maybe they could be in the same
examples, as one is a wrapper for the other.  Just an example, not
necessarily a good one.

Some specific comments below, but I'm on board with OO.



On Mon, Feb 12, 2018 at 6:26 PM, Hannah <story645 at gmail.com> wrote:
>
>
> On Mon, Feb 12, 2018 at 8:56 PM, Chris Barker - NOAA Federal
> <chris.barker at noaa.gov> wrote:
>>
>>
>> but calling methods on existing objects is not: you can’t get very far in
>> python without using the methods of the buil-ins: lists, dicts, strings....
>
>
> I agree that you can't get very far in Python without it, but it still
> majorly confuses the audiences I work with. Quite literally, the demarcation
> my fellowship makes between the Python 101 and 201 we teach is how
> explicitly we go into using objects. So I think an intro should provide at
> least a soft explanation of methods/objects/etc.
>
>>
>>  they're all pyplot, but that seems to be the preferred intro-and I wonder
>> if it'd be good for matplotlib to have more bridge documentation that
>> doesn't just show how to do things both ways but explains why the OO way is
>> better.
>>
>>
>> Yup. And I don’t think pyplot is any easier for newbies—other than
>> existing Matlab users — admittedly a big group.
The biggest issue I had with pyplot was finding it's limitations.  I
saw that coloring every marker a different color on a line is
possible, which leads me to the documentation for various objects, but
I eventually find that I can't do that with pyplot, I can only provide
one color per line.  There's a mix of undocumented features and
undocumented limitations (or maybe I couldn't find them, but even
then).   stackexchange has an API to search questions, at some point
will be fun/impossible to mine it.
>
>
> It is and it isn't. While it's technically still OO, I think it ends up
> feeling weirdly declarative just keep layering these things (kinda like
> ggplot), rather than the explicit here's an axis and attach information to
> it. It seems like a super trivial distinction but I think it may be a
> barrier for some people (also why I think a survey could be good here.)
>
>>
>> I say introduce the OO interface, then have a “matplotlib for Matlab
>> users” section to translate for them.
>
> I like this approach too.
Agree, users don't need to know they are Object Oriented programming.
I believe Ben created a single image with everything labeled (tick,
marker, etc).  Learning the words/labels might be a sufficient
understanding of Plot Objects without requiring OO programming.  Just
programming with Plot Objects.  Which object to start with?  I was
thinking Figure because if the first thing you "see" and then drilling
down, but not at all married to it.  That could be considered
backwards but at the end of the day Figure is what get's modified so a
narrative arc about what's happening to the figure might work.

>
>
> _______________________________________________
> Matplotlib-devel mailing list
> Matplotlib-devel at python.org
> https://mail.python.org/mailman/listinfo/matplotlib-devel
>