Merge pull request #30 from stevepiercy/docs_filesystem_checks

Docs filesystem checks

CONTRIBUTORS.txt

@@ -116,4 +116,6 @@ Michael Merickel, 2013-10-19
 
 Maxim Avanov, 2014-01-28
 
+Jonathan Vanasco, 2015-01-09
+
 Steve Piercy, 2015-01-20

docs/index.rst

@@ -182,6 +182,34 @@ variable set to ``1``, For example:
 
    $ PYRAMID_RELOAD_TEMPLATES=1 bin/pserve myproject.ini
 
+.. note::
+
+    If you are already familiar with the Mako Templating Language, then you
+    should be aware that configuration options for Pyramid and Mako may cause
+    some confusion.
+
+    Pyramid offers a universal ``pyramid.reload_templates`` setting to manage
+    similar functionality across multiple template systems.
+
+    Pyramid's ``reload_templates`` is essentially a proxy to Mako's
+    ``filesystem_checks`` configuration option (with support for some other
+    Pyramid-specific features built in).  If ``reload_templates`` is set to
+    ``True``, Pyramid will pass ``filesystem_checks = True`` to Mako (and
+    vice-versa).
+
+    Traditionally in Mako, a ``TemplateLookup`` instance will have the default
+    value ``filesystem_checks = True`` and one must explicitly disable this
+    behavior.  However, Pyramid's default behvavior is for ``reload_templates``
+    to be ``None``, which Mako will treat as a ``False`` value for this
+    setting.
+
+    Because of this difference, the Mako integration of ``pyramid_mako`` may
+    not initially behave as you expect it would.  Mako's ``filesystem_checks``
+    are disabled by default and must be explicitly enabled by setting
+    ``pyramid.reload_templates`` to ``true``.  You can also affect
+    ``reload_templates`` with the environment variable
+    ``PYRAMID_RELOAD_TEMPLATES`` as described above.
+
 A Sample Mako Template
 ----------------------