Improve documentation for examples/widgets/textbox.py

[chrissshe]

PR Summary

The current documentation in textbox.py doesn't explicitly explain that this is an interactive GUI. Its name textbox may be easily confused with normal text with box, which is probably used more often. And it's hard to tell otherwise from the embedded screenshot. It fooled me for a good minute at least. I added a few notes in docstring and comment to stress the fact that this is different than just inserting a static text box. Also to bring more clarity to the purpose of the "submit" function.

This PR is also related to #11654

PR Checklist

• Has Pytest style unit tests
• Code is Flake 8 compliant
• New features are documented, with examples if plot related
• Documentation is sphinx and numpydoc compliant
• Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
• Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

[timhoffm]

Thanks for the contribution!

Please do not leave trailing whitespace. Our style checker does not like that:

./examples/widgets/textbox.py:8:75: W291 trailing whitespace
./examples/widgets/textbox.py:9:79: W291 trailing whitespace
./examples/widgets/textbox.py:12:30: W291 trailing whitespace
./examples/widgets/textbox.py:13:39: W291 trailing whitespace
./examples/widgets/textbox.py:29:76: W291 trailing whitespace
./examples/widgets/textbox.py:31:23: W291 trailing whitespace

[chrissshe]

I don't see any specific error in the failed CI... help is appreciated!

[timhoffm]

For travis, click on the failed job (flake8 in this case) and inspect the log:

./examples/widgets/textbox.py:9:52: W291 trailing whitespace

You can ignore failures in the nightly build.

Similarly, for CircleCI (which we use for doc-building), click on the failed job. Check the messages in the "Build documentation" section. Usually, it's a good idea to download that log and search for "WARNING" with a text editor. This gives:

/home/circleci/project/doc/gallery/widgets/textbox.rst:14: WARNING: py:obj reference target not found: submit
/home/circleci/project/doc/gallery/widgets/textbox.rst:19: WARNING: py:obj reference target not found: Textbox

[story645]

Those are probably my fault 'cause I didn't properly format my snippet in rest. the guidelines are here: https://matplotlib.org/devel/documenting_mpl.html#writing-docstrings

Optimally on_submit should be cross referenced against it's docs. I don't know how to format the reference to submit - it should be differentiated from plaintext but it's a user written function.

[chrissshe]

@timhoffm I did download the circleci log but I only searched for error not warning :( And I didn't proceed to check the Travis. Thank you for providing the details
@story645 I will look into the cross-referencing later today. If no other way around, maybe I'll just remove this specific referencing in the introduction.

[story645]

Reading that warning message again, looks like `.on_submit` was found, which agrees with the cross link guideance since it was unambiguous.

To fix the warnings, I think the following replacements should work:

`Textbox` with with `.Textbox` 
 `submit` with :code: `submit` 

[chrissshe]

@story645 following that guideline you sent, I figured out the right way to do it. It has to be

matplotlib.widgets.TextBox and submit

[chrissshe]

The new commit addressed all failures and I think it's ready to merge

[story645]

Thanks for your contribution! 🚀