doc/provider: python virtualenvs #6135

Closes #1887

Helped-by: Tommy Allen <tommy@esdf.io>

runtime/doc/provider.txt

@@ -49,7 +49,8 @@ Note: The `--upgrade` flag ensures you have the latest version even if
 PYTHON PROVIDER CONFIGURATION ~
 						*g:python_host_prog*
 						*g:python3_host_prog*
-Program to use for evaluating Python code. Setting this makes startup faster. >
+Program to use for evaluating Python code. Setting this makes startup faster.
+Also useful for working with virtualenvs.  >
     let g:python_host_prog  = '/path/to/python'
     let g:python3_host_prog = '/path/to/python3'
 <
@@ -61,6 +62,23 @@ To disable Python 2 support: >
 To disable Python 3 support: >
     let g:loaded_python3_provider = 1
 
+PYTHON VIRTUALENVS ~
+
+If you plan to use per-project virtualenvs often, you should assign
+a virtualenv for Neovim and hard-code the interpreter path via
+|g:python_host_prog| (or |g:python3_host_prog|) so that the "neovim" python
+package is not required for each Environment. Example using pyenv: >
+    pyenv install 3.4.4
+    pyenv virtualenv 3.4.4 py3neovim
+    pyenv activate py3neovim
+    pip install neovim
+    pyenv which python  # Note the path
+
+The last command reports the interpreter path. Add it to your init.vim: >
+    let g:python3_host_prog = '/full/path/to/py3neovim/bin/python'
+
+More information:
+https://github.com/zchee/deoplete-jedi/wiki/Setting-up-Python-for-Neovim
 
 ==============================================================================
 Ruby integration		    	      *provider-ruby*
@@ -80,7 +98,6 @@ RUBY PROVIDER CONFIGURATION ~
 To disable Ruby support: >
     let g:loaded_ruby_provider = 1
 
-
 ==============================================================================
 Clipboard integration 			      *provider-clipboard* *clipboard*
 
@@ -93,7 +110,7 @@ are found in your `$PATH`.
 
   - xclip
   - xsel (newer alternative to xclip)
-  - pbcopy/pbpaste (Mac OS X)
+  - pbcopy/pbpaste (macOS)
   - lemonade (for SSH) https://github.com/pocke/lemonade
   - doitclient (for SSH) http://www.chiark.greenend.org.uk/~sgtatham/doit/