Rewrite warning to note about Venusian scanning limitations

1 files changed, 16 insertions, 11 deletions

diff --git a/src/pyramid/view.py b/src/pyramid/view.py
index bcda13733..65d81b8d0 100644
--- a/src/pyramid/view.py
+++ b/src/pyramid/view.py
@@ -196,21 +196,26 @@ class view_config:
         See also :ref:`mapping_views_using_a_decorator_section` for
         details about using :class:`pyramid.view.view_config`.
 
-    .. warning::
+    .. note::
 
-        ``view_config`` will work ONLY on module top level members
-        because of the limitation of ``venusian.Scanner.scan``.
+        Because of the limitation of ``venusian.Scanner.scan``, note that
+        ``view_config`` will work only for the following conditions.
 
-        Also it will ONLY work on views present as plaintext python
-        files (*.py), ignoring all non-*.py ones which also includes
-        *.pyc and *.pyo (python precompiled byte code / optimized) files.
+        -   In Python packages that have an ``__init__.py`` file in their
+            directory.
 
-        Another venusian specific precondition to take into account is that
-        python packages to be found by venusian need to have a __init__.py
-        file in their root directory.
+            .. seealso::
 
-        This is a limitation in venusian documented in:
-        https://docs.pylonsproject.org/projects/venusian/en/latest/#using-venusian
+                See also https://github.com/Pylons/venusian/issues/68
+
+        -   On module top level members.
+        -   On Python source (``.py``) files.
+            Compiled Python files (``.pyc``, ``.pyo``) without a corresponding
+            source file are ignored.
+        .. seealso::
+
+            See also the `Venusian documentation
+            <https://docs.pylonsproject.org/projects/venusian/en/latest/#using-venusian>`_.
     """
 
     venusian = venusian  # for testing injection