Add to documentation that adjust_text() needs to be called last!

[lrq3000]

Hey there,

It's a very very useful library, but I banged my head so many times trying to use it that I find I unfortunate that it could have saved so many hours if the documentation was a bit more guiding, and I guess most users either lost a lot of time like me or just dropped the library in frustration.

I feel the documentation should be updated to at least include:

1. the function signature (name of function, arguments, docstring -- the latter will be a quite convenient replacement for a documentation until a proper one is redacted)
2. a simple example (just something basic like your first example -- if possible outside of a function to avoid confusing new users as much as possible, unnecessary constructs should be kept at a minimum for a minimal quickstart example)
3. add an important note: For consistent behavior and best display results, adjust_text() should be called last, after drawing the whole figure, the labels and resizing. To do that, simply store all text objects in a list texts, and call adjust_text(texts) just before plt.show().

I think this last note is the most important of all additions to the readme, as calling adjust_text() anytime before is bound to produce undefined behavior, which is not specified in a clear manner anywhere.

Indeed, even if one calls adjust_text() only on a subset of text objects, it will still produce erratic behavior, like text moved far away from points (I could not pinpoint the root cause), or outside the boundary of the image (the latter only if the image gets resized afterward).

[Phlya]

Hi, thank you for your comments - you are absolutely right, the documentation is currently basically non-existent, but I don't think I currently have time to develop it properly... I would be happy merge PRs that would address this in any way! I'll try to specifically add the points you are raising here.

I thought the last point should be quite obvious (of course we can't adjust positions of texts if the axes are not set up properly, and we don't know their future limits!), but you are not the first person to mention this, so I guess you are right and this should be written explicitly.

[Phlya]

Please see whether the newly added wiki addresses your concerns, and feel free to improve it!

[lrq3000]

@Phlya Thank you for your enthousiasm and for putting something on the wiki this fast :-) This addresses points 2 and 3 but not point 1. I will try to do a PR in the upcoming days for the readme, but already the wiki will surely help :-)

[Phlya]

You are right of course, the docstring should be converted to numpydoc format too... Thank you for the ideas again, and hope to see your PR soon then :)

[Phlya]

I think it's sufficiently clear now.