pygrass: utils.set_path function fix revert https://trac.osgeo.org/grass/changeset/66637, setting sys.path to handle local path and add docstring to clarify the use

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@67659 15284696-431f-4ddb-bdfa-cd5b030d7da7

lib/python/pygrass/utils.py

@@ -308,16 +308,67 @@ def get_lib_path(modname, libname=None):
         path = join('etc', modname)
     else:
         path = None
-    
+
     return path
 
 
 def set_path(modulename, dirname=None, path='.'):
     """Set sys.path looking in the the local directory GRASS directories.
 
-    @param modulename
-    @param dirname
-    @param path used to run the code locally without compilation
+    :param modulename: string with the name of the GRASS module
+    :param dirname: string with the directory name containing the python
+                    libraries, default None
+    :param path: string with the path to reach the dirname locally.
+
+    Example
+    --------
+
+    "set_path" example working locally with the source code of a module
+    (r.green) calling the function with all the parameters. Below it is
+    reported the directory structure on the r.green module.
+
+    ::
+
+        grass_prompt> pwd
+        ~/Download/r.green/r.green.hydro/r.green.hydro.financial
+
+        grass_prompt> tree ../../../r.green
+        ../../../r.green
+        ├── ...
+        ├── libgreen
+        │   ├── pyfile1.py
+        │   └── pyfile2.py
+        └── r.green.hydro
+           ├── Makefile
+           ├── libhydro
+           │   ├── pyfile1.py
+           │   └── pyfile2.py
+           ├── r.green.hydro.*
+           └── r.green.hydro.financial
+               ├── Makefile
+               ├── ...
+               └── r.green.hydro.financial.py
+
+        21 directories, 125 files
+
+    in the source code the function is called with the following parameters: ::
+
+        set_path('r.green', 'libhydro', '..')
+        set_path('r.green', 'libgreen', os.path.join('..', '..'))
+
+    when we are executing the module: r.green.hydro.financial locally from
+    the command line:  ::
+
+        grass_prompt> python r.green.hydro.financial.py --ui
+
+    In this way we are executing the local code even if the module was already
+    installed as grass-addons and it is available in GRASS standards path.
+
+    The function is cheching if the dirname is provided and if the
+    directory exists and it is available using the path
+    provided as third parameter, if yes add the path to sys.path to be
+    importable, otherwise it will check on GRASS GIS standard paths.
+
     """
     import sys
     # TODO: why dirname is checked first - the logic should be revised
@@ -325,8 +376,9 @@ def set_path(modulename, dirname=None, path='.'):
     if dirname:
         pathlib = os.path.join(path, dirname)
     if pathlib and os.path.exists(pathlib):
-        # we are running the script from the script directory
-        sys.path.append(os.path.abspath(pathlib))
+        # we are running the script from the script directory, therefore
+        # we add the path to sys.path to reach the directory (dirname)
+        sys.path.append(os.path.abspath(path))
     else:
         # running from GRASS GIS session
         path = get_lib_path(modulename, dirname)