Add doc section and use case for "BuildSources" method in extra scripts

Resolve #209

Author: valeros

projectconf/advanced_scripting.rst

@@ -938,3 +938,34 @@ install them into the same virtual environment where :ref:`piocore` is installed
 
     # Install custom packages from the PyPi registry
     env.Execute("$PYTHONEXE -m pip install pkg1 pkg2")
+
+Build external sources
+^^^^^^^^^^^^^^^^^^^^^^
+
+If your project depends on some arbitrary source files that are located outside of the
+usual source directory :ref:`projectconf_pio_src_dir` then you can use a preliminary
+extra script to add them to the build process. A typical situation when this approach
+may be useful is when a project depends on pregenerated files in a temporary folder.
+Here is a typical configuration with an extra_script that instructs PlatformIO to build
+all sources in an external folder:
+
+``platformio.ini``:
+
+.. code-block:: ini
+
+    [env:my_env]
+    platform = ...
+    extra_scripts = pre:extra_script.py
+
+``extra_script.py`` (place it near ``platformio.ini``):
+
+.. code-block:: python
+
+    import os
+
+    Import("env")
+
+    env.BuildSources(
+        os.path.join("$BUILD_DIR", "external", "build"),
+        os.path.join("$PROJECT_DIR", "external", "sources")
+    )