Added fixes for docs / nested test for use of sys.path in toolpath

1 files changed, 31 insertions, 18 deletions

diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index 4657c05..ae670a8 100644
--- a/doc/user/environments.xml
+++ b/doc/user/environments.xml
@@ -1781,7 +1781,7 @@ env.AppendENVPath('LIB', '/usr/local/lib')
       </para>
 
       <sconstruct>
-# Inbuilt tool or tool located within site_tools
+# Builtin tool or tool located within site_tools
 env = Environment(tools = ['SomeTool'])
 env.SomeTool(targets, sources)
 
@@ -1847,11 +1847,12 @@ SCons/Tool/SubDir1/SubDir2/SomeTool/__init__.py
       </sconstruct>
 
       <para>
-      It's important to note when creating tools within sub-directories,
-	  there needs to be a __init__.py file within each directory.
-	  This file can just be empty.
-	  This is the same constraint used by python when loading modules
-	  from within sub-directories (packages).
+      For python2 It's important to note when creating tools within sub-directories,
+      there needs to be a __init__.py file within each directory.
+      This file can just be empty.
+      This is the same constraint used by python when loading modules
+      from within sub-directories (packages).
+      For python3 this appears to be no longer a requirement.
       </para>
     </section>
 
@@ -1859,20 +1860,30 @@ SCons/Tool/SubDir1/SubDir2/SomeTool/__init__.py
     <title>Using sys.path within the toolpath</title>
 
       <para>
-      Using the toolpath option with sys.path
-	  we can also include tools installed via the pip package manager.
-	  </para>
+      If we want to access tools externally to scons on the sys.path
+      (one example would be tools installed via the pip package manager)
+      One way to do this is to use sys.path with the toolpath.
+
+      One thing to watch out for with this approach is that sys.path
+      can sometimes contains paths to .egg files instead of directories.
+      So we need to filter those out with this approach.
+      </para>
 
       <sconstruct>
 # namespaced target using sys.path within toolpath
-env = Environment(tools = ['someinstalledpackage.SomeTool'], toolpath = sys.path)
+
+searchpaths = []
+for item in sys.path:
+    if os.path.isdir(item): searchpaths.append(item)
+
+env = Environment(tools = ['someinstalledpackage.SomeTool'], toolpath = searchpaths)
 env.SomeTool(targets, sources)
       </sconstruct>
 
       <para>
-      By supplying sys.path to the toolpath argument
-	  and by using the nested syntax we can have scons search
-	  the sys.path (which will include packages installed via pip).
+      By using sys.path with the toolpath argument
+      and by using the nested syntax we can have scons search
+      packages installed via pip for Tools.
       </para>
 
 <sconstruct>
@@ -1893,19 +1904,21 @@ C:\Python35\Lib\site-packages\someinstalledpackage\SomeTool\__init__.py
       <para>
       In some cases you may want to use a tool
       located within a installed external pip package.
-      This is possible by the use of sys.path within the toolpath.
-      However in that situaion you need to provide a prefix to the toolname
+      This is possible by the use of sys.path with the toolpath.
+      However in that situation you need to provide a prefix to the toolname
       to indicate where it is located within sys.path
       </para>
 
       <sconstruct>
-# namespaced target using sys.path
-env = Environment(tools = ['tools_example.subdir1.subdir2.SomeTool'], toolpath = sys.path)
+searchpaths = []
+for item in sys.path:
+    if os.path.isdir(item): searchpaths.append(item)
+env = Environment(tools = ['tools_example.subdir1.subdir2.SomeTool'], toolpath = searchpaths)
 env.SomeTool(targets, sources)
       </sconstruct>
 
       <para>
-      To avoid the use of a prefix within the name of the tool,
+      To avoid the use of a prefix within the name of the tool or filtering sys.path for directories,
       we can use the <function>PyPackageDir(modulename)</function> function to locate the directory of the python package.
       <function>PyPackageDir</function> returns a Dir object which represents the path of the directory
       for the python package / module specified as a parameter.