Merge pull request #1224 from pallets/loader-docs

update package and filesystem loader docs

2 files changed, 42 insertions, 27 deletions

diff --git a/docs/api.rst b/docs/api.rst
index 53cb03b5..ec083a8a 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -25,30 +25,40 @@ initialization and use that to load templates.  In some cases however, it's
 useful to have multiple environments side by side, if different configurations
 are in use.
 
-The simplest way to configure Jinja to load templates for your application
-looks roughly like this::
+The simplest way to configure Jinja to load templates for your
+application is to use :class:`~loaders.PackageLoader`.
+
+.. code-block:: python
 
     from jinja2 import Environment, PackageLoader, select_autoescape
     env = Environment(
-        loader=PackageLoader('yourapplication', 'templates'),
-        autoescape=select_autoescape(['html', 'xml'])
+        loader=PackageLoader("yourapp"),
+        autoescape=select_autoescape()
     )
 
-This will create a template environment with the default settings and a
-loader that looks up the templates in the `templates` folder inside the
-`yourapplication` python package.  Different loaders are available
-and you can also write your own if you want to load templates from a
-database or other resources.  This also enables autoescaping for HTML and
-XML files.
+This will create a template environment with a loader that looks up
+templates in the ``templates`` folder inside the ``yourapp`` Python
+package (or next to the ``yourapp.py`` Python module). It also enables
+autoescaping for HTML files. This loader only requires that ``yourapp``
+is importable, it figures out the absolute path to the folder for you.
+
+Different loaders are available to load templates in other ways or from
+other locations. They're listed in the `Loaders`_ section below. You can
+also write your own if you want to load templates from a source that's
+more specialized to your project.
+
+To load a template from this environment, call the :meth:`get_template`
+method, which returns the loaded :class:`Template`.
+
+.. code-block:: python
 
-To load a template from this environment you just have to call the
-:meth:`get_template` method which then returns the loaded :class:`Template`::
+    template = env.get_template("mytemplate.html")
 
-    template = env.get_template('mytemplate.html')
+To render it with some variables, call the :meth:`render` method.
 
-To render it with some variables, just call the :meth:`render` method::
+.. code-block:: python
 
-    print(template.render(the='variables', go='here'))
+    print(template.render(the="variables", go="here"))
 
 Using a template loader rather than passing strings to :class:`Template`
 or :meth:`Environment.from_string` has multiple advantages.  Besides being
diff --git a/src/jinja2/loaders.py b/src/jinja2/loaders.py
index 09f678d7..6b71b835 100644
--- a/src/jinja2/loaders.py
+++ b/src/jinja2/loaders.py
@@ -137,25 +137,30 @@ class BaseLoader:
 
 
 class FileSystemLoader(BaseLoader):
-    """Loads templates from the file system.  This loader can find templates
-    in folders on the file system and is the preferred way to load them.
+    """Load templates from a directory in the file system.
 
-    The loader takes the path to the templates as string, or if multiple
-    locations are wanted a list of them which is then looked up in the
-    given order::
+    The path can be relative or absolute. Relative paths are relative to
+    the current working directory.
 
-    >>> loader = FileSystemLoader('/path/to/templates')
-    >>> loader = FileSystemLoader(['/path/to/templates', '/other/path'])
+    .. code-block:: python
+
+        loader = FileSystemLoader("templates")
 
-    Per default the template encoding is ``'utf-8'`` which can be changed
-    by setting the `encoding` parameter to something else.
+    A list of paths can be given. The directories will be searched in
+    order, stopping at the first matching template.
 
-    To follow symbolic links, set the *followlinks* parameter to ``True``::
+    .. code-block:: python
 
-    >>> loader = FileSystemLoader('/path/to/templates', followlinks=True)
+        loader = FileSystemLoader(["/override/templates", "/default/templates"])
+
+    :param searchpath: A path, or list of paths, to the directory that
+        contains the templates.
+    :param encoding: Use this encoding to read the text from template
+        files.
+    :param followlinks: Follow symbolic links in the path.
 
     .. versionchanged:: 2.8
-       The ``followlinks`` parameter was added.
+        Added the ``followlinks`` parameter.
     """
 
     def __init__(self, searchpath, encoding="utf-8", followlinks=False):