Add documentation about working in virtualenvs to the Matplotlib faq #5179
Conversation
In the framework error message within the OSX backend
| ============ | ||
|
|
||
| When running :mod:`matplotlib` in a virtual environment you may discover a | ||
| few issues. :mod:`matplotlib` itself works problemless in virtual envirnments. |
There was a problem hiding this comment.
"mpl itself has no issue with virtual environments." ?
|
attn @mdehoon |
|
|
||
| When running :mod:`matplotlib` in a virtual environment you may discover a | ||
| few issues. :mod:`matplotlib` itself works problemless in virtual envirnments. | ||
| However, the GUI frameworks that :mod:`matplotlib` depends uses for interactive |
|
@tacaswell and @efiring Thanks for the prof reading. I have corrected the typos that you spotted. I am also interested in if people thinks this is understandable from a technical point of view? Given that we have added the check to the OSX backend that makes it error out inside a virtual env I think it is very important that we add some docs about it before the release which are understandable. We have already had a few bug reports about this in the rc's |
| <https://github.com/pypa/virtualenv/issues/54>`__ and `here | ||
| <https://github.com/pypa/virtualenv/issues/609>`__ | ||
|
|
||
| Until this is fixed a work around is needed. The best known work around, |
There was a problem hiding this comment.
"workaround" should be one word : e.g. https://en.wiktionary.org/wiki/workaround
|
I agree that this is needed, and I think it is reasonably understandable. Some writing tweaks could still be made. Regarding the more important aspect, the substance: I'm a little concerned about advocating |
| some familiarity with the Matplotlib backends as found in :ref:`What is a | ||
| backend? <what-is-a-backend>`. | ||
|
|
||
| If you only use the ``IPython/Jupyter`` inline and ``notebook/nbagg`` backends |
There was a problem hiding this comment.
The inline also needs the backticks, and notebook/nbagg might be notebook or (alias) nbagg. Correct? Otherwise, I have a little trouble parsing this, and realizing that it is very specific; just using the Jupyter notebook, for example, is not enough. This is in contrast to ordinary gui operations, in which using IPython or the notebook tends to solve all problems, regardless of backend. (Well, most, anyway.)
There was a problem hiding this comment.
Yes, I have changed that to hopefully make it more clear.
|
I agree about the |
|
It is completely necessary to error out in a virtualenv for MacOSX backend? Presumably it would in fact work - as it did in 1.4.3? |
|
That was the decision made by @mdehoon and I tend to agree with it. The issue is that the figure window cannot be bought to the foreground and seemingly random parts of the interaction with the figure doesn't work resulting in puzzling bug reports which are hard to debug |
|
Oh dear - that will be a problem for me, I use the OSX backend a lot. How about a non-default rcparam to enable the OSX backend in virtualenvs? |
|
Does the OSX backend work better in conda environments? |
|
AFAIK Conda envs have the same issue. I don't think a RC param to enable something which is fundamentally broken is a good idea. I would suggest to use the |
|
We can consider changing it to a warning if people prefer that? |
| Introduction | ||
| ============ | ||
|
|
||
| When running :mod:`matplotlib` in a virtual environment you may discover a |
There was a problem hiding this comment.
We should probably start with links to what we're talking about.
https://virtualenv.pypa.io/en/latest/
or, in Python 3.3 and later:
There was a problem hiding this comment.
Sorry I must have missed this. I will fix if asap
|
This is good. Reminds me why I sometimes want to throw Macs across the room, but I think this will be very helpful. |
|
If conda envs are affected the same way, should note that here? I use the OSX backend very often in light virtualenvs, so any option that allows me to take responsibility for the risk of OSX misbehavior in a virtualenv would be very good. |
|
@matthew-brett It seems like conda envs work correctly so I have updated the document to reflect this |
|
@matthew-brett I don't have any strong opinion if this should be a warning or an error but this PR is only about the documentation |
|
Anything else I need to do here? I think the question of warning vs error should be handled outside this PR |
|
Other than my one inline comment about linking to virtualenv docs, I think this is good to go. I agree, let's keep this documentation-only, and think about warnings vs. exceptions later. |
|
I have added the links to the virtualenv docs and a link to an alternative workaround |
|
Thanks! |
Add documentation about working in virtualenvs to the Matplotlib faq
The writing could probably still use some work.