Include python-file using the real path

When layout_config points to a symbolic link, Zuul attempted to load the
python function from directory of the symbolic link instead of the
parent of the link target.  That causes the scheduled to halt.

* Use realpath on layout_config path to make sure we will load from the
  proper place.
* Update documentation of python-file to mention the include is relative
  to the directory holding layout_config.

Change-Id: I33e221dd7c323423dbf781b53c06333dab2c7d29
diff --git a/doc/source/zuul.rst b/doc/source/zuul.rst
index 6cb5d59..6cfdc50 100644
--- a/doc/source/zuul.rst
+++ b/doc/source/zuul.rst
@@ -86,6 +86,8 @@
 zuul
 """"
 
+.. _layout_config:
+
 **layout_config**
   Path to layout config file.  Used by zuul-server only.
   ``layout_config=/etc/zuul/layout.yaml``
@@ -272,10 +274,12 @@
     - python-file: local_functions.py
 
 **python-file**
-  The path to a python file.  The file will be loaded and objects that
-  it defines will be placed in a special environment which can be
-  referenced in the Zuul configuration.  Currently only the
-  parameter-function attribute of a Job uses this feature.
+  The path to a python file (either an absolute path or relative to the
+  directory name of :ref:`layout_config <layout_config>`).  The
+  file will be loaded and objects that it defines will be placed in a
+  special environment which can be referenced in the Zuul configuration.
+  Currently only the parameter-function attribute of a Job uses this
+  feature.
 
 Pipelines
 """""""""
diff --git a/zuul/scheduler.py b/zuul/scheduler.py
index 9effcb8..def7429 100644
--- a/zuul/scheduler.py
+++ b/zuul/scheduler.py
@@ -226,7 +226,7 @@
             if 'python-file' in include:
                 fn = include['python-file']
                 if not os.path.isabs(fn):
-                    base = os.path.dirname(config_path)
+                    base = os.path.dirname(os.path.realpath(config_path))
                     fn = os.path.join(base, fn)
                 fn = os.path.expanduser(fn)
                 execfile(fn, config_env)