- Document filesystem caching for Chameleon page templates

CHANGES.rst

@@ -23,8 +23,15 @@ Fixes
 - Don't error out when showing permissions for a non-existent user
   (`#437 <https://github.com/zopefoundation/Zope/issues/437>`_)
 
+Other changes
++++++++++++++
+
+- Document filesystem caching for Chameleon page templates
+  (`#291 <https://github.com/zopefoundation/Zope/issues/291>`_)
+
 Breaking changes
 ++++++++++++++++
+
 - Removed support for ``management_page_charset``
  (`#313 <https://github.com/zopefoundation/Zope/issues/313>`_)
 

docs/zope2book/AdvZPT.rst

@@ -1202,6 +1202,29 @@ caching for performance-critical applications.
 For more information on caching in the context of Zope, see the
 chapter entitled `Zope Services <ZopeServices.html>`_.
 
+Filesystem caching for Chameleon-based templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Zope 4 introduced the `Chameleon HTML/XML template engine
+<https://chameleon.readthedocs.io/>`_ as new backend for Zope Page
+Templates. The Chameleon templating engine can compile templates and
+cache them on the file system for faster startup and execution.
+
+File system caching is activated by setting an environment variable
+named ``CHAMELEON_CACHE`` to the path of a folder on the filesystem
+where Chameleon can write its compiled template representation.
+
+Look for or add a section named ``environment`` in ``etc/wsgi.conf``
+and add a suitable filesystem path, for example::
+
+  <environment>
+    CHAMELEON_CACHE $INSTANCE/var/cache
+  </environment>
+
+Make sure that folder exists before starting Zope.
+
+How to configure Zope is explained in `Configuring Zope <../operation.html>`_.
+
 Page Template Utilities
 -----------------------
 

src/Zope2/utilities/skel/etc/wsgi.conf.in

@@ -35,6 +35,23 @@ instancehome $INSTANCE
 #    locale fr_FR
 
 
+# Directive: environment
+#
+# Description:
+#     A section which can be used to define arbitrary key-value pairs
+#     for use as environment variables during Zope's run cycle.  It
+#     is not recommended to set system-related environment variables such as
+#     PYTHONPATH within this section.
+#
+# Default: unset
+#
+# Example:
+#
+#    <environment>
+#      CHAMELEON_CACHE $INSTANCE/var/cache
+#    </environment>
+
+
 # Directive: debug-mode
 #
 # Description: