From 96f137b8319c639937f4617920f96763e013213d Mon Sep 17 00:00:00 2001
From: grbd <garlicbready@googlemail.com>
Date: Mon, 19 Jun 2017 15:45:03 +0100
Subject: Updated the documentation for nested tools located within subdirs

---
 doc/man/scons.xml             | 16 +++++++++++++++
 doc/user/builders-writing.xml | 47 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+)

(limited to 'doc')

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index b68f27ae..3268860b 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -2187,6 +2187,22 @@ platform name when the Environment is constructed. Changing the PATH
 variable after the Environment is constructed will not cause the tools to
 be redetected.</para>
 
+<para> One feature now present within Scons is the ability to have nested tools.
+Tools which can be located within a subdirectory in the toolpath.
+With a nested tool name the dot represents a directory seperator</para>
+
+<programlisting>
+# namespaced builder
+env = Environment(ENV = os.environ, tools = ['SubDir1.SubDir2.SomeTool'])
+env.SomeTool(targets, sources)
+
+# Search Paths
+# SCons\Tool\SubDir1\SubDir2\SomeTool.py
+# SCons\Tool\SubDir1\SubDir2\SomeTool\__init__.py
+# .\site_scons\site_tools\SubDir1\SubDir2\SomeTool.py
+# .\site_scons\site_tools\SubDir1\SubDir2\SomeTool\__init__.py
+</programlisting>
+
 <para>SCons supports the following tool specifications out of the box:</para>
 
 <!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -->
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index 07f2dec6..35dd989d 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.xml
@@ -880,6 +880,53 @@ env2.Foo('file2')
 
   </section>
 
+  <section>
+  <title>Nested and namespace builders;</title>
+
+    <para>
+    &SCons; now supports the ability for a Builder to be located within a sub-directory of the toolpath.
+	This is similar to namespacing within python.
+
+    Normally when loading a tool into the environment, scons will search for the tool within two locations
+    </para>
+
+    <sconstruct>
+# Regular non namespace target
+env = Environment(ENV = os.environ, tools = ['SomeTool'])
+env.SomeTool(targets, sources)
+    </sconstruct>
+
+    <para>
+    The locations would include
+	<filename>SCons\Tool\SomeTool.py</filename>
+    <filename>SCons\Tool\SomeTool\__init__.py</filename>
+    <filename>.\site_scons\site_tools\SomeTool.py</filename>
+	<filename>.\site_scons\site_tools\SomeTool\__init__.py</filename>
+
+    If a toolpath is specified this is also searched as well.
+	With nested or namespaced tools we can use the dot notation to specify a sub-directoty that the tool is located under
+    </para>
+
+    <sconstruct>
+# namespaced target
+env = Environment(ENV = os.environ, tools = ['SubDir1.SubDir2.SomeTool'])
+env.SomeTool(targets, sources)
+    </sconstruct>
+
+    <para>
+    With this example the search locations would include
+	<filename>SCons\Tool\SubDir1\SubDir2\SomeTool.py</filename>
+    <filename>SCons\Tool\SubDir1\SubDir2\SomeTool\__init__.py</filename>
+    <filename>.\site_scons\site_tools\SubDir1\SubDir2\SomeTool.py</filename>
+	<filename>.\site_scons\site_tools\SubDir1\SubDir2\SomeTool\__init__.py</filename>
+
+    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 however.
+	This is the same constraint used by python when loading modules from within sub-directories (packages).
+
+    </para>
+  </section>
+
   <!--
 
   <section>
-- 
cgit v1.2.1