Tweak WorkerTmpDir docs

docs/source/faq.rst

@@ -161,6 +161,8 @@ How do I fix Django reporting an ``ImproperlyConfigured`` error?
 With asynchronous workers, creating URLs with the ``reverse`` function of
 ``django.core.urlresolvers`` may fail. Use ``reverse_lazy`` instead.
 
+.. _blocking-os-fchmod:
+
 How do I avoid Gunicorn excessively blocking in ``os.fchmod``?
 --------------------------------------------------------------
 

docs/source/settings.rst

@@ -376,6 +376,14 @@ A directory to use for the worker heartbeat temporary file.
 
 If not set, the default temporary directory will be used.
 
+.. note::
+   The current heartbeat system involves calling ``os.fchmod`` on
+   temporary file handlers and may block a worker for arbitrary time
+   if the directory is on a disk-backed filesystem.
+
+   See :ref:`blocking-os-fchmod` for more detailed information
+   and a solution for avoiding this problem.
+
 user
 ~~~~
 

gunicorn/config.py

@@ -982,10 +982,13 @@ class WorkerTmpDir(Setting):
 
         If not set, the default temporary directory will be used.
 
-        Warning: the current heartbeat system involves calling ``os.fchmod`` on
-        temporary file handlers and may block a worker for arbitrary time if the
-        directory is on a disk-backed filesystem. See the :ref:`faq` for more
-        detailed information and a solution for avoiding this problem.
+        .. note::
+           The current heartbeat system involves calling ``os.fchmod`` on
+           temporary file handlers and may block a worker for arbitrary time
+           if the directory is on a disk-backed filesystem.
+
+           See :ref:`blocking-os-fchmod` for more detailed information
+           and a solution for avoiding this problem.
         """