Merge pull request #501 from pwnage101/docs-invocation-from-root

docs: clarify locust invocation norms

docs/quickstart.rst

@@ -74,28 +74,30 @@ as well as other user behaviours.
 Start Locust
 ============
 
-To run Locust with the above locust file, if it was named *locustfile.py*, we could run 
-(in the same directory as locustfile.py)::
+To run Locust with the above locust file, if it was named *locustfile.py* and located in the current working
+directory, we could run::
 
     locust --host=http://example.com
 
-or if the locust file is located elsewhere we could run::
+If the locust file is located under a subdirectory and/or named different than *locustfile.py*, specify
+it using ``-f``::
 
-    locust -f ../locust_files/my_locust_file.py --host=http://example.com
+    locust -f locust_files/my_locust_file.py --host=http://example.com
 
-To run Locust distributed across multiple processes we would start a master process by specifying --master::
+To run Locust distributed across multiple processes we would start a master process by specifying
+``--master``::
 
-    locust -f ../locust_files/my_locust_file.py --master --host=http://example.com
+    locust -f locust_files/my_locust_file.py --master --host=http://example.com
 
 and then we would start an arbitrary number of slave processes::
 
-    locust -f ../locust_files/my_locust_file.py --slave --host=http://example.com
+    locust -f locust_files/my_locust_file.py --slave --host=http://example.com
 
 If we want to run locust distributed on multiple machines we would also have to specify the master host when
 starting the slaves (this is not needed when running locust distributed on a single machine, since the master 
 host defaults to 127.0.0.1)::
 
-    locust -f ../locust_files/my_locust_file.py --slave --master-host=192.168.0.100 --host=http://example.com
+    locust -f locust_files/my_locust_file.py --slave --master-host=192.168.0.100 --host=http://example.com
 
 .. note::
 

docs/writing-a-locustfile.rst

@@ -292,7 +292,7 @@ called client that simply returns self.locust.client.
 
 
 Using the HTTP client
-======================
+----------------------
 
 Each instance of HttpLocust has an instance of :py:class:`HttpSession <locust.clients.HttpSession>` 
 in the *client* attribute. The HttpSession class is actually a subclass of 
@@ -364,3 +364,60 @@ Example::
     # Statistics for these requests will be grouped under: /blog/?id=[id]
     for i in range(10):
         client.get("/blog?id=%i" % i, name="/blog?id=[id]")
+
+Common libraries
+=================
+
+Often, people wish to group multiple locustfiles that share common libraries.  In that case, it is important
+to define the *project root* to be the directory where you invoke locust, and it is suggested that all
+locustfiles live somewhere beneath the project root.
+
+A flat file structure works out of the box:
+
+* project root
+
+  * ``commonlib_config.py``
+
+  * ``commonlib_auth.py``
+
+  * ``locustfile_web_app.py``
+
+  * ``locustfile_api.py``
+
+  * ``locustfile_ecommerce.py``
+
+The locustfiles may import common libraries using, e.g. ``import commonlib_auth``.  This approach does not
+cleanly separate common libraries from locust files, however.
+
+Subdirectories can be a cleaner approach (see example below), but locust will only import modules relative to
+the directory in which the running locustfile is placed. If you wish to import from your project root (i.e. the
+location where you are running the locust command), make sure to write ``sys.path.append(os.getcwd())`` in your
+locust file(s) before importing any common libraries---this will make the project root (i.e. the current
+working directory) importable.
+
+* project root
+
+  * ``__init__.py``
+
+  * ``common/``
+
+    * ``__init__.py``
+
+    * ``config.py``
+
+    * ``auth.py``
+
+  * ``locustfiles/``
+
+    * ``__init__.py``
+
+    * ``web_app.py``
+
+    * ``api.py``
+
+    * ``ecommerce.py``
+
+With the above project structure, your locust files can import common libraries using::
+
+    sys.path.append(os.getcwd())
+    import common.auth