More improved troubleshooting

docs/source/installation/troubleshooting-common.rst

@@ -131,3 +131,29 @@ Solution to this problem is simple: be sure that :file:`z.sh` is sourced
 strictly after :file:`powerline/bindings/bash/powerline.sh`. This way background 
 jobs are spawned by `z <https://github.com/rupa/z>`_ after powerline has done 
 its job.
+
+
+I am experiencing problems after update
+---------------------------------------
+
+First, check out that you have only one powerline installed. Do
+
+    .. code-block:: vim
+
+       python import powerline
+       python print(powerline.__file__)
+
+(replace ``python`` with ``python3`` if appropriate) and check out that printed 
+file location is the one you have recently updated. If it is not you have the 
+following alternatives:
+
+* Always remember to update all installations of powerline you have.
+* (Here and below I assume you have double vim and pip installation.) Use code 
+  from first paragraph of :ref:`vim-vimrc` section and remove vim installation.
+* Remove existing pip installation and use
+
+    .. code-block:: sh
+
+       pip install -e ~/.vim/bundle/powerline
+
+  to reinstall.

docs/source/overview.rst

@@ -93,10 +93,12 @@ Installation
 Usage
 =====
 
+.. _vim-vimrc:
+
 Vim statusline
 --------------
 
-If installed using pip just use
+If installed using pip just add
 
 .. code-block:: vim
 
@@ -104,7 +106,7 @@ If installed using pip just use
     python powerline_setup()
     python del powerline_setup
 
-(replace ``python`` with ``python3`` if appropriate).
+(replace ``python`` with ``python3`` if appropriate) to your :file:`vimrc`.
 
 If you just cloned the repository add the following line to your :file:`vimrc`, 
 where ``{repository_root}`` is the absolute path to your Powerline installation 

powerline/bindings/vim/plugin/powerline.vim

@@ -29,6 +29,7 @@ try
 	unlet s:pystr
 	let s:launched = 1
 finally
+	unlet s:import_cmd
 	if !exists('s:launched')
 		echohl ErrorMsg
 			echom 'An error occurred while importing powerline package.'
@@ -38,6 +39,42 @@ finally
 			echom 'the troubleshooting section in the documentation for'
 			echom 'possible solutions.'
 		echohl None
+		let s:pystr  = "def powerline_troubleshoot():\n"
+		let s:pystr .= "	import sys\n"
+		let s:pystr .= "	if sys.version_info < (2, 6):\n"
+		let s:pystr .= "		print('Too old python version: ' + sys.version + ' (first supported is 2.6)')\n"
+		let s:pystr .= "	elif sys.version_info[0] == 3 and sys.version_info[1] < 2:\n"
+		let s:pystr .= "		print('Too old python 3 version: ' + sys.version + ' (first supported is 3.2)')\n"
+		let s:pystr .= "	try:\n"
+		let s:pystr .= "		import powerline\n"
+		let s:pystr .= "	except ImportError:\n"
+		let s:pystr .= "		print('Unable to import powerline, is it installed?')\n"
+		if expand('<sfile>')[:4] isnot# '/usr/'
+			let s:pystr .= "	else:\n"
+			let s:pystr .= "		import os\n"
+			let s:pystr .= "		powerline_dir = os.path.dirname(os.path.realpath(powerline.__file__))\n"
+			let s:pystr .= "		this_dir = os.path.dirname(os.path.realpath(vim.eval('expand(\"<sfile>:p\")')))\n"
+			let s:pystr .= "		this_dir = os.path.dirname(os.path.dirname(os.path.dirname(this_dir)))\n"
+			let s:pystr .= "		if os.path.basename(this_dir) != 'powerline':\n"
+			let s:pystr .= "			print('Check your installation:')\n"
+			let s:pystr .= "			print('this script is not in powerline[/bindings/vim/plugin] directory,')\n"
+			let s:pystr .= "			print('neither it is installed system-wide')\n"
+			let s:pystr .= "		this_dir = os.path.dirname(this_dir)\n"
+			let s:pystr .= "		real_powerline_dir = os.path.realpath(powerline_dir)\n"
+			let s:pystr .= "		real_this_dir = os.path.realpath(this_dir)\n"
+			let s:pystr .= "		if real_this_dir != sys.path[-1]:\n"
+			let s:pystr .= "			print('Check your installation:')\n"
+			let s:pystr .= "			print('this script is symlinked somewhere where powerline is not present.')\n"
+			let s:pystr .= "		elif real_powerline_dir != real_this_dir:\n"
+			let s:pystr .= "			print('It appears that you have two powerline versions installed:')\n"
+			let s:pystr .= "			print('one in ' + real_powerline_dir + ', other in ' + real_this_dir + '.')\n"
+			let s:pystr .= "			print('You should remove one of this. Check out troubleshooting section,')\n"
+			let s:pystr .= "			print('it contains some information about the alternatives.')\n"
+		endif
+		execute s:pycmd s:pystr
+		unlet s:pystr
+		unlet s:pycmd
+		unlet s:pyeval
 		finish
 	else
 		unlet s:launched
@@ -47,3 +84,6 @@ endtry
 execute s:pycmd 'import vim'
 execute s:pycmd 'powerline_setup(pyeval=vim.eval("s:pyeval"), pycmd=vim.eval("s:pycmd"))'
 execute s:pycmd 'del powerline_setup'
+
+unlet s:pycmd
+unlet s:pyeval