Sphinx and docstring fixes

2 files changed, 34 insertions, 25 deletions

diff --git a/pyparsing/exceptions.py b/pyparsing/exceptions.py
index d92212d..978e3d1 100644
--- a/pyparsing/exceptions.py
+++ b/pyparsing/exceptions.py
@@ -36,11 +36,6 @@ class ParseBaseException(Exception):
 
         Returns a multi-line string listing the ParserElements and/or function names in the
         exception's stack trace.
-
-        Note: the diagnostic output will include string representations of the expressions
-        that failed to parse. These representations will be more helpful if you use `setName` to
-        give identifiable names to your expressions. Otherwise they will use the default string
-        forms, which may be cryptic to read.
         """
         import inspect
         from .core import ParserElement
@@ -101,9 +96,9 @@ class ParseBaseException(Exception):
 
     def __getattr__(self, aname):
         """supported attributes by name are:
-           - lineno - returns the line number of the exception text
-           - col - returns the column number of the exception text
-           - line - returns the line containing the exception text
+            - lineno - returns the line number of the exception text
+            - col - returns the column number of the exception text
+            - line - returns the line containing the exception text
         """
         if aname == "lineno":
             return lineno(self.loc, self.pstr)
@@ -178,6 +173,14 @@ class ParseBaseException(Exception):
                     ^
             ParseException: Expected W:(0-9), found 'A'  (at char 8), (line:1, col:9)
 
+        Note: the diagnostic output will include string representations of the expressions
+        that failed to parse. These representations will be more helpful if you use `setName` to
+        give identifiable names to your expressions. Otherwise they will use the default string
+        forms, which may be cryptic to read.
+
+        Note: pyparsing's default truncation of exception tracebacks may also truncate the
+        stack of expressions that are displayed in the ``explain`` output. To get the full listing
+        of parser expressions, you may have to set ``ParserElement.verbose_stacktrace = True``
         """
         return self.explain_exception(self, depth)
 
@@ -186,9 +189,9 @@ class ParseException(ParseBaseException):
     """
     Exception thrown when parse expressions don't match class;
     supported attributes by name are:
-    - lineno - returns the line number of the exception text
-    - col - returns the column number of the exception text
-    - line - returns the line containing the exception text
+     - lineno - returns the line number of the exception text
+     - col - returns the column number of the exception text
+     - line - returns the line containing the exception text
 
     Example::
 
@@ -210,8 +213,6 @@ class ParseFatalException(ParseBaseException):
     """user-throwable exception thrown when inconsistent parse content
        is found; stops all parsing immediately"""
 
-    pass
-
 
 class ParseSyntaxException(ParseFatalException):
     """just like :class:`ParseFatalException`, but thrown internally
@@ -220,8 +221,6 @@ class ParseSyntaxException(ParseFatalException):
     syntax error has been found.
     """
 
-    pass
-
 
 # ~ class ReparseException(ParseBaseException):
 # ~ """Experimental class - parse actions can raise this exception to cause
diff --git a/pyparsing/results.py b/pyparsing/results.py
index 0eeb9f6..8390459 100644
--- a/pyparsing/results.py
+++ b/pyparsing/results.py
@@ -42,10 +42,12 @@ class ParseResults:
 
         integer = Word(nums)
         date_str = (integer.setResultsName("year") + '/'
-                        + integer.setResultsName("month") + '/'
-                        + integer.setResultsName("day"))
+                    + integer.setResultsName("month") + '/'
+                    + integer.setResultsName("day"))
         # equivalent form:
-        # date_str = integer("year") + '/' + integer("month") + '/' + integer("day")
+        # date_str = (integer("year") + '/'
+        #             + integer("month") + '/'
+        #             + integer("day"))
 
         # parseString returns a ParseResults object
         result = date_str.parseString("1999/12/31")
@@ -225,10 +227,13 @@ class ParseResults:
 
         Example::
 
+            numlist = Word(nums)[...]
+            print(numlist.parseString("0 123 321")) # -> ['0', '123', '321']
+
             def remove_first(tokens):
                 tokens.pop(0)
-            print(OneOrMore(Word(nums)).parseString("0 123 321")) # -> ['0', '123', '321']
-            print(OneOrMore(Word(nums)).addParseAction(remove_first).parseString("0 123 321")) # -> ['123', '321']
+            numlist.addParseAction(remove_first)
+            print(numlist.parseString("0 123 321")) # -> ['123', '321']
 
             label = Word(alphas)
             patt = label("LABEL") + OneOrMore(Word(nums))
@@ -296,12 +301,14 @@ class ParseResults:
 
         Example::
 
-            print(OneOrMore(Word(nums)).parseString("0 123 321")) # -> ['0', '123', '321']
+            numlist = Word(nums)[...]
+            print(numlist.parseString("0 123 321")) # -> ['0', '123', '321']
 
             # use a parse action to insert the parse location in the front of the parsed results
             def insert_locn(locn, tokens):
                 tokens.insert(0, locn)
-            print(OneOrMore(Word(nums)).addParseAction(insert_locn).parseString("0 123 321")) # -> [0, '0', '123', '321']
+            numlist.addParseAction(insert_locn)
+            print(numlist.parseString("0 123 321")) # -> [0, '0', '123', '321']
         """
         self._toklist.insert(index, insStr)
         # fixup indices in token dictionary
@@ -317,12 +324,14 @@ class ParseResults:
 
         Example::
 
-            print(OneOrMore(Word(nums)).parseString("0 123 321")) # -> ['0', '123', '321']
+            numlist = Word(nums)[...]
+            print(numlist.parseString("0 123 321")) # -> ['0', '123', '321']
 
             # use a parse action to compute the sum of the parsed integers, and add it to the end
             def append_sum(tokens):
                 tokens.append(sum(map(int, tokens)))
-            print(OneOrMore(Word(nums)).addParseAction(append_sum).parseString("0 123 321")) # -> ['0', '123', '321', 444]
+            numlist.addParseAction(append_sum)
+            print(numlist.parseString("0 123 321")) # -> ['0', '123', '321', 444]
         """
         self._toklist.append(item)
 
@@ -338,7 +347,8 @@ class ParseResults:
             def make_palindrome(tokens):
                 tokens.extend(reversed([t[::-1] for t in tokens]))
                 return ''.join(tokens)
-            print(patt.addParseAction(make_palindrome).parseString("lskdj sdlkjf lksd")) # -> 'lskdjsdlkjflksddsklfjkldsjdksl'
+            patt.addParseAction(make_palindrome)
+            print(patt.parseString("lskdj sdlkjf lksd")) # -> 'lskdjsdlkjflksddsklfjkldsjdksl'
         """
         if isinstance(itemseq, ParseResults):
             self.__iadd__(itemseq)