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

diff --git a/doc/user/environments.xml b/doc/user/environments.xml
index 4657c054a62636614f29232ad5eb8a347219e3d8..ae670a80411c1ae2ba4589884b624c937245762c 100644 (file)
--- 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.

diff --git a/test/toolpath/nested/image/SConstruct b/test/toolpath/nested/image/SConstruct
index 78ae21d9b424c243dbe19f923a079db862eea858..a7c6ceb7d21796cbaa24a26d47e17ce48c90cb7e 100644 (file)
--- a/test/toolpath/nested/image/SConstruct
+++ b/test/toolpath/nested/image/SConstruct
@@ -39,6 +39,10 @@ dir_path = Dir('.').srcnode().abspath
 dir_path = os.path.join(dir_path, 'Libs')\r
 sys.path.append(dir_path)\r
 \r
+searchpaths = []\r
+for item in sys.path:\r
+    if os.path.isdir(item): searchpaths.append(item)\r
+\r
 toollist = ['tools_example.Toolpath_TestTool1',\r
             'tools_example.Toolpath_TestTool2',\r
             'tools_example.subdir1.Toolpath_TestTool1_1',\r
@@ -47,7 +51,7 @@ toollist = ['tools_example.Toolpath_TestTool1',
             'tools_example.subdir1.subdir2.Toolpath_TestTool2_2',\r
            ]\r
 \r
-env3 = Environment(tools=toollist, toolpath=sys.path)\r
+env3 = Environment(tools=toollist, toolpath=searchpaths)\r
 print("env3['Toolpath_TestTool1'] =", env3.get('Toolpath_TestTool1'))\r
 print("env3['Toolpath_TestTool2'] =", env3.get('Toolpath_TestTool2'))\r
 print("env3['Toolpath_TestTool1_1'] =", env3.get('Toolpath_TestTool1_1'))\r