cleanup bin-script creation, fix docs, add FAQ entry about py.test --version

--HG--
branch : trunk

CHANGELOG

@@ -8,6 +8,9 @@ Changes between 1.1.2 and 1.1.1
 
 - skip some install-tests if no execnet is available
 
+- fix docs, fix internal bin/ script generation
+
+
 Changes between 1.1.1 and 1.1.0
 =====================================
 

bin-for-dist/genscripts.py

@@ -1,6 +1,6 @@
-from _findpy import py
+import py
 
-bindir = py.magic.autopath().dirpath().dirpath("py").join("bin")
+bindir = py.path.local(__file__).dirpath().dirpath("bin")
 assert bindir.check(), bindir
 
 def getbasename(name):
@@ -31,5 +31,3 @@ if __name__ == "__main__":
         if name[0] != "_":
             genscript_unix(name)
             genscript_windows(name)
-        
-        

bin/_findpy.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python 
 
 #
-# find and import a version of 'py'
+# find and import a version of 'py' that exists in a parent dir
+# of the current working directory. fall back to import a 
+# globally available version
 #
 import sys
 import os

doc/faq.txt

@@ -63,6 +63,15 @@ issues where people have used the term "magic" in the past:
 .. _`py namespaces`: index.html
 .. _`py/__init__.py`: http://bitbucket.org/hpk42/py-trunk/src/trunk/py/__init__.py
 
+Where does my ``py.test`` come/import from? 
+----------------------------------------------
+
+You can issue::
+
+    py.test --version
+
+which tells you both version and import location of the tool.
+
 
 function arguments, parametrized tests and setup
 ====================================================

doc/install.txt

@@ -116,37 +116,33 @@ in order to work inline with the tools and the lib of your checkout.
 
 .. _`directly use a checkout`: 
 
-directly use a checkout or tarball 
+directly use a checkout or tarball / avoid setuptools 
 -------------------------------------------------------------
 
-Once you got yourself a checkout_ or tarball_ it is usually a good 
+Get a checkout_ or tarball_ and add paths to your environment variables:
-idea to add the parent directory of the ``py`` package directory 
-to your ``PYTHONPATH`` and ``py/bin`` or ``py\bin\win32`` to your 
-system wide ``PATH`` settings.  There are helper scripts that 
-set ``PYTHONPATH`` and ``PATH`` on your system: 
 
-on windows execute::
+* ``PYTHONPATH`` needs to contain the root directory (where ``py`` resides)
+* ``PATH`` needs to contain ``ROOT/bin`` or ``ROOT\bin\win32`` respectively. 
+
+There also are helper scripts that set the variables accordingly.  On windows 
+execute::
 
     # inside autoexec.bat or shell startup
     c:\\path\to\checkout\bin\env.cmd
 
 on linux/OSX add this to your shell initialization:: 
 
-    # inside .bashrc 
+    # inside e.g. .bashrc 
     eval `python ~/path/to/checkout/bin/env.py` 
 
-both of which which will get you good settings 
+both of which which will get you good settings.  If you install 
-for ``PYTHONPATH`` and ``PATH``.
+the pylib this way you can easily ``hg pull && hg up`` or download
+a new tarball_ to follow the development tree.
 
-If you install ``py.test`` this way you can easily
-``hg pull && hg up`` your checkout to follow the
-development tree.
 
-note: scripts look for "nearby" py-lib 
+Note that the scripts manually added like this will look for 
------------------------------------------------------
+py libs in the chain of parent directories of the current working dir.  
-
+For example, if you have a layout like this::
-Note that all `command line scripts`_ will look 
-for "nearby" py libs, so if you have a layout like this::
 
     mypkg/
         subpkg1/
@@ -155,13 +151,12 @@ for "nearby" py libs, so if you have a layout like this::
     py/
 
 issuing ``py.test subpkg1`` will use the py lib
-from that projects root directory.   Giving the
+from that projects root directory.   If in doubt over where
-state of Python packaging there can be confusion
+the pylib comes from you can always do::
-in which case issuing::
 
     py.test --version
 
-tells you both version and import location of the tool.
+to see where py.test is imported from. 
 
 .. _`command line scripts`: bin.html
 .. _contact: contact.html