[Matplotlib-devel] Documentation

[Matt Arcidy]

Hi all,

Sorry for the long wait, but I have some results to show.

Attached is programmatically generated ranking of  the examples based
on python complexity.

It was done by using the ast module to get every  statement, then each
file was ranked by a method I completely made up, but that can fit
whatever need we have.

It's very basic analysis compared to what is possible, so the ranking
here aren't perfect by any means.  I have not included ranking
matplotlib difficulty as that will require expert input.  As a funny
example,  contour3d.py comes up as one of the easiest tutorials.
That's because the code is easy., the concepts are much harder.
Ranking the mpl objects will provide a much richer and more useful
output.  And of course any dimension we think of can be ranked.

I'm not sure if this _output_ is useful as much as it's a proof of
concept.  But the examples do rank by python complexity now, so that's
good.  I included the ranking algorithm (ranking.py) to show how it
works and what is possible.  I'm doing really naive things like
existence and counts, but even that works to a degree.

There is plenty more information to use that is not in this run: class
inheritance, statement complexity (e.g. # of nested statements in one
expression), number lines of code, number of imports, etc.  many
things are available to use as factors.

Once the ranking is good, creating learning paths can be done,
allowing people to learn python in tandem to mpl, by creating paths
that introduce only 1 or 2 new items, be it a new arg to pyplot or an
object relatively close to another one in an inheritance tree.
Anything that can be programmatically found.  Or perhaps gaps will be
found as well.

And likewise, I can pull out any symbol to use as a search term or a
tag.  I can detect if they are from matplotlib package, or an external
package, and a list probably needs to be maintained to keep track of
what is considered complex and why, but that's a small price I think.

Feedfback?

More than happy to talk anyone's head off about it but I would like to
know if this is useful, and if so, what direction to take first, and
get it focused on specific tasks, etc..


as a note:
This can be used for much more, as I built it to do deep inspection
for other tasks mentioned.  For example, it can be used to look into
doc strings and check that all arguments of the function are in the
doc string.  It can go even further to look at the function body and
see if any arguments are consumed as literals, and then check if those
literals are mentioned in the docs.  And that can all be traced
through any call or attribute assignment (even dict keys, slicing,
etc) and trace things back to an entry point.  Entry point being a
script or scanning the whole package.  At this stage i have the core
functionality to do that, but those functions need to be built.

I also need to write tests and documentation (ha).  And I called it
doctor_doctor which is highly subject to change.


On Tue, Feb 13, 2018 at 4:20 PM, Matt Arcidy <marcidy at gmail.com> wrote:
> I will add args inspection to my Sphinx hacking.  That will also let me
> discriminate functions calls by tutorial/example as well, plus add that info
> to search parameters.  plt.plot() usage in examples will greatly benefit
> from this.
>
> On Tue, Feb 13, 2018, 15:24 Hannah <story645 at gmail.com> wrote:
>>
>>
>>> For instance, the first time a keyword argument is used, a link to a
>>> brief tutorial on keyword arguments. If people want to know more, they
>>> follow that link -- if they already understand kw args, then then skip on
>>> by...
>>
>>
>> I think this approach has a good balance of not reinventing the wheel
>> while also sign posting,
>>
>> And Matt, I think  creating a narrative of this is a figure, on a figure
>> we put axes, could probably go a ways towards helping with the "why?" of it
>> all.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: ranking.py
Type: text/x-python
Size: 4277 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180316/2b4df5a7/attachment-0001.py>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: rankings-test.csv
Type: text/csv
Size: 17333 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20180316/2b4df5a7/attachment-0001.csv>