Documentation?

[Achifaifa]

Just a fairly generic question, but I haven't found anything at all.

I want to do certain things with the diagram and I wanted to look at a list of all the functions/attributes/etc in the library I can fiddle with. ¿Is there such a thing? I've solved everything so far by looking at stackoverflow and guessing things from the examples in the readme but honestly, it takes too much time and I'd rather read a few pages of documentation and be done with it.

I like libraries to have that kind of documentation (Saves LOTS of time), so let me know if I can help to get this done.

[konstantint]

At the moment there is the README in this project (which is copied to the PyPI package) and I believe it covers pretty much everything you might want to "fiddle with".

Anything outside that scope would be internal details which are not "safe to fiddle" in the sense that there is a probability that some of the future versions would rewrite all of that and you'll get your code broken. Hence if you really need to fiddle, you better be ready to look at the source code and maybe even copy it to your own project.

Maybe I am missing something - what kind of additional documentation would you expect to have?

[Achifaifa]

What I'm trying to say is that the readme has a few examples and you have to infer everything from them (Mostly from the complex three group diagram), which is not practical.

I'm talking about something in the lines of the python documentation. A listing of all the functions, parameters and options you can use, and maybe a page with a few examples, including those in the readme (Like this).

It's not a big library and I think it's doable (And reasonable to start documenting before it gets out of hand :))

[konstantint]

I'm still not sure what exactly do you mean by "start documenting before it gets out of hand". At the moment pretty much every single function in the code, big or small, has a pydoc along with doctests for examples. Consequently, you can type pydoc matplotlib_venn.venn2, for example, and get the detailed description of the function with parameters and the like, if you need it.

If you're into old-school browser interfaces, pydoc -p 8080 would serve you the same docs in a browser.

Alternatively, any proper IDE will provide you with the same information if you hover your mouse in the appropriate place or click where necessary.

Finally, if you, like most people, work with matplotlib from within ipython/jupyter, you typically type something like venn2? whenever you need to see the help. If you use the usual python shell, help(venn2) does the same.

If you suggest that an additional copy still of the same docs should none the less be up on readthedocs or the like, I'll consider setting it up, however, I must admit I personally do not see the overwhelming benefits of such a setup beyond a proper README. Let me explain why.

Note that this package provides a total of 6 (six) interface functions. Moreover, all of them are essentially variations of just 1 (one!) function. The usage of a single function along with its minor variations can be described rather concisely in a single manpage-style text along with examples.

Consequently, if you do think that the current README is insufficient, I would be grateful if you would bring particular questions that are not answered by it, and I'd try fixing the README to cover those aspects before even bothering to set up a readthedocs or the like.

[Achifaifa]

Ouch, I didn't think about using ipython's inline help. Nice, thanks :).

In the end I did figure out my issue using the readme. It took a while, but I guess it can be done after all. My main concrete issue with readmes is that, even if they are complete, they always feel like you are missing something. For example, in

>>> v.get_patch_by_id('100').set_alpha(1.0)
>>> v.get_patch_by_id('100').set_color('white')
>>> v.get_label_by_id('100').set_text('Unknown')

I just don't (didn't) know if those were all possible functions or just an example to show usage. So the first thing I thought of was "OK, where is the list with the rest of the functions?". Hence the python docs page I linked.

Anyway, now that I get it I agree with you, the readme is enough for a small library, but I'd still mention the jupyter/ipython help and the fact that nothing is missing and all the functionality of the library is listed in the readme. Just in case :)

[konstantint]

OK, I'll add that information to the README then, thanks!

[alexlenail]

@konstantint I'd agree with @Achifaifa . Given how well you've documented the code, I believe it makes sense to use something like autodoc (or read the docs) to build a site for the documentation of this package. I think that's conventional for a library of this popularity, where most people will be pip installing instead of cloning and combing through the source.

My use case is: in jupyter, how do I resize the figure? (or more generally, how do I access the plot object?)

[konstantint]

Well, I do still believe that README (i.e. whatever you can read at the pypi page) really contains everything there is to say about the usage, and in the rare case you need per-function doc, inline help does the job.

This understanding makes me reluctant to bother setting up a readthedocs or the like (despite being "automatic", documentation generators still require quite some manual work and thought to make a useful documentation site - making a useless documentation site using "out of the box" tools seems meaningless to me).

You are welcome to contribute, though. Set up the docs dir with the necessary sphinx templates and settings, and I'll happily merge those in and put up on readthedocs.

As far as your question is concerned, you would not find your answer in the docs for matplotlib-venn anyway. The figure size is given to the matplotlib figure command. E.g.:

figure(figsize = (15, 10))

[alexlenail]

@konstantint Sounds good. But first, for my problem: how do I access the figure object to change the figsize?

venn3([A, B, C], figsize=(10,10))    # no
venn3([A, B, C]).figsize=(10,10)    # no
...?

[konstantint]

Whenever you type "plot" in the notebook, what actually happens under the hood is approximately the following:

gcf().gca().plot(...)

Where gcf() is "get current figure" and gca() means "get current axes". If you type plot at the time when no figure was previously created, matplotlib initializes it for you with some defaults and creates a default axes on it. If you do not like the defaults you can redefine them later:

gcf().set_figheight(10)
gcf().set_figwidth(10)

You can also take figure creation in your own hands and call figure(figsize=(10, 10)) before plotting anything - the gcf() function will then refer to that exact figure you just created.

To summarize. Either do (the usual approach)

figure(figsize=(10, 10))
venn3(...)

or (less usual but still valid approach)

venn3(...)
gcf().set_figheight(10)
...

PS: Note that the gcf, gca and figure functions are part of matplotlib.pyplot namespace. They are imported in the notebook automatically if you type %pylab inline.