I am +0 on this patch. We're making things complicated because people use conda without understanding the underlying python packaging system. We're putting duck tape instead of teaching people about paths and imports.

Nelle - I don't think this is a conda-specific patch. I've certainly hit this where I'm working in a virtualenv, and I accidentally call a sphinx installed into the system or user directories.

wait… You don't set up virtualenv to be a completely independant environment ?

(Anyhow, I am not against this patch, but I don't think we are solving the underlying problem).

Well sphinx-build goes by default to /usr/bin/sphinx-build (or equivalent) (and it refers to /usr/bin/python, not /usr/bin/env python -- exactly as it wants to be run in whatever environment it was installed, not whatever environment is active) so unless you want to remove /usr/bin from your PATH (...) when you activate your venv it's still going to be a problem.

It's a question of which one comes first in the path. The local one should always come before /usr/bin. Technically, it should not be a problem unless sphinx is not installed in the local one.

If it is not installed in the local one, then users are having exactly the same problem as running an ipython shell outside of the environment, or pip outside of the environment.

IPython actually has code to specifically handle that case, which prints a warning and tries to manipulate the PATH correctly (init_virtualenv in interactiveshell.py).

/usr/lib/python3.6/site-packages/IPython/core/interactiveshell.py:724: UserWarning: Attempting to work in a virtualenv. If you encounter problems, please install IPython inside the virtualenv.
  warn("Attempting to work in a virtualenv. If you encounter problems, please "

venvs created by python -mvenv now default to installing pip so unless you get rid of it on purpose (... or are using an ancient version...) you won't have that problem.

Nelle - when I use virtualenvwrapper I have initialization scripts that pull the Python --user binary install directory off the PATH, but when I use virtualenv alone, I have to remember to do that by hand. But it seems reasonable to make this easy mistake less easy, if possible.

I am 👍 on this.

As a side note, if we up the dependency on sphinx to 1.3 (which is needed for this to work, and part of the PR), that also means we have sphinx.ext.napoleon available which can be used instead of numpydoc.

See #5743 (in need of update, though.)