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

doc/source/zuul.rst

@@ -86,6 +86,8 @@ gerrit
 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 @@ include, and currently supports one type of inclusion, a python file::
     - python-file: local_functions.py
 
 **python-file**
-  The path to a python file.  The file will be loaded and objects that
+  The path to a python file (either an absolute path or relative to the
-  it defines will be placed in a special environment which can be
+  directory name of :ref:`layout_config <layout_config>`).  The
-  referenced in the Zuul configuration.  Currently only the
+  file will be loaded and objects that it defines will be placed in a
-  parameter-function attribute of a Job uses this feature.
+  special environment which can be referenced in the Zuul configuration.
+  Currently only the parameter-function attribute of a Job uses this
+  feature.
 
 Pipelines
 """""""""

zuul/scheduler.py

@@ -226,7 +226,7 @@ class Scheduler(threading.Thread):
             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)