Added -OO note

2 files changed, 23 insertions, 0 deletions

diff --git a/README.md b/README.md
index 8f5ba11..787dd46 100644
--- a/README.md
+++ b/README.md
@@ -107,6 +107,10 @@ PLY requires the use of Python 3.6 or greater.  However, you should
 use the latest Python release if possible.  It should work on just
 about any platform.  
 
+Note: PLY does not support execution under `python -OO`.  It can be
+made to work in that mode, but you'll need to change the programming
+interface with a decorator.  See the documentation for details. 
+
 Resources
 =========
 
diff --git a/docs/ply.rst b/docs/ply.rst
index 2f6a89a..2bad85a 100644
--- a/docs/ply.rst
+++ b/docs/ply.rst
@@ -2640,6 +2640,25 @@ For very complicated problems, you should pass in a logging object that
 redirects to a file where you can more easily inspect the output after
 execution.
 
+Using Python -OO Mode
+---------------------
+Because of PLY's reliance on doc-strings, it is not compatible with
+`-OO` mode of the interpreter (which strings doc strings).  If you
+want to support this, you'll need to write a decorator or some other
+tool to attach doc strings to functions.  For example:
+
+    def _(doc):
+        def decorate(func):
+            func.__doc__ = doc
+            return func
+        return decorate
+    
+    @_("assignment : expr PLUS expr")
+    def p_assignment(p):
+        ...
+
+PLY does not provide such a decorator by default.
+
 Where to go from here?
 ----------------------