Add examples for every geom

[pintergreg]

I do think there should be a minimal working example for every geom_* with an image to demonstrate what can one do with them similarly how it is done in ggplot2's website.
In some cases it causes me a lot of work to figure out (e.g. get the info from the source) how things work (I have not read the Grammar of Graphics book and I'm novice in ggplot2 as well because I work with Python). The documentation should be much more expressive and the gallery should contain everyday examples not just some fancy techdemo (as for me, I don't really plot periodic table so often).

The v0.3.0 tells me plotnine is in its early stage of development (but a really useful tool as it is now already and I started to like it), so this might not be the first priority. I put this on my agenda (as well), hence I could learn it even more, but I do not see when I will be able to start working on it...

[has2k1]

Plotnine matches the ggplot2 API as closely as the language allows and there are plenty ggplot2 examples around, so the priority for the documentation is to show the power of the package. The results of such plots are what go in the gallery -- to show-off --, but they are constructed to teach the user.

... (as for me, I don't really plot periodic table so often)

The periodic table is just an example of highly organised tabular information (see the caption, it is not just about fancy stuff).

Even for the examples that are not "worthy of the gallery", the goal is for them to be a part of something slightly larger e.g. an analysis where it is clear that the geom choice is the best. The guide lines say as much, but perhaps still a little vague.

Then there is a tutorials section for among other things the painful little issues that one may bump into. For users completely new to all this, there will be a introductory tutorial. Even this one could slant towards a graphical exploratory analysis.

Such criteria, means that the the documentation may be short of examples in the short term, but hopefully in the long term it should be a quality repository on how to use the package effectively.

The v0.3.0 tells me plotnine is in its early stage of development ...

Inferring development status from the version number can be misleading.

It would be helpful for a new user like you to keep notes of your learning process. Things like what concepts are alien at the start, the common mistakes you make, when are your expectations defied, what terms do you search for but do not lead you the answers you want, etc. Such insight can help improve the documentation.

[pintergreg]

The ..n.. and ..prop.. options was hard to find for example. The docstrings describes them, and they are the same as in ggplot2, but I did not know their existence before. I had to search specifically for ggplot2 to solve my problem when I got to know them.

I do know plotnine semantics is the same as ggplot2, that's why I started to use, but as someone who is not even familiar with ggplot2 it is hard to start with plotnine because I found the documentation pretty vague. To be precise it is for someone who is familiar with the grammar of graphics, not for rookies.

Matplotlib documentation on the other hand is almost like a picture book where you can choose by plots and see the code that produces it and it is better for novices in my opinion. At least I like to learn by examples. My point is plotnine should have much basic tutorials with simple things for people who's just started to use this plotting library.

For users completely new to all this, there will be a introductory tutorial. Even this one could slant towards a graphical exploratory analysis.

This will be awesome.

[khaeru]

An idea: plotnine.doctools already exists to munge docstrings before they go to Sphinx to be rendered. It seems to do things like substitute content where placeholders like {superclass_parameters} are found.

This module could be enhanced to:

1. For any class like geom_path to be documented, look for a file like doc/example/geom_path.rst.
2. If it exists, append its contents (with an Examples header) to the class docstring.

This would allow contributors to add in these examples by pull requests, but in a separate directory from the main code, making these easy to review.

[has2k1]

@khaeru, that is kind of how plotnine-examples are integrated into the documentation. They are pulled in by a sphinx extension.

The basic examples will go to that repo. There is some reorganisation that I need to think about i.e how to separate the examples that lead to plots that show up in the gallery; at the moment it is not that obvious.

[jtrakk]

I want to be recommending this package often, but I always have to tell people they should use the R ggplot2 docs, which tends to put them off if they don't know R, and they usually end up using matplotlib or seaborn.

I wonder if the R ggplot2 docs could be (mostly) automatically converted to use plotnine, which would likely reduce the amount of effort required to port. Either way, having more complete documentation would be a major boon to the library IMHO.