Docstring formatting changes (#197)

* Tidy docstring formatting for lists and example codeblock

* Add class references and formatting to docstrings

* Experimental docstring formatting changes

5 files changed, 69 insertions, 54 deletions

diff --git a/pyparsing/__init__.py b/pyparsing/__init__.py
index ae2d822..0a92801 100644
--- a/pyparsing/__init__.py
+++ b/pyparsing/__init__.py
@@ -36,7 +36,7 @@ grammar directly in Python.
 Here is a program to parse "Hello, World!" (or any greeting of the form
 ``"<salutation>, <addressee>!"``), built up using :class:`Word`,
 :class:`Literal`, and :class:`And` elements
-(the :class:`'+'<ParserElement.__add__>` operators create :class:`And` expressions,
+(the :meth:`'+'<ParserElement.__add__>` operators create :class:`And` expressions,
 and the strings are auto-converted to :class:`Literal` expressions)::
 
     from pyparsing import Word, alphas
@@ -52,7 +52,8 @@ The program outputs the following::
     Hello, World! -> ['Hello', ',', 'World', '!']
 
 The Python representation of the grammar is quite readable, owing to the
-self-explanatory class names, and the use of '+', '|' and '^' operators.
+self-explanatory class names, and the use of :class:`'+'<And>`,
+:class:`'|'<MatchFirst>`, :class:`'^'<Or>` and :class:`'&'<Each>` operators.
 
 The :class:`ParseResults` object returned from
 :class:`ParserElement.parseString` can be
diff --git a/pyparsing/core.py b/pyparsing/core.py
index 806ee73..d9f277c 100644
--- a/pyparsing/core.py
+++ b/pyparsing/core.py
@@ -200,8 +200,10 @@ def conditionAsParseAction(fn, message=None, fatal=False):
     to an operator level in infixNotation).
 
     Optional keyword arguments:
+
     - message = define a custom message to be used in the raised exception
     - fatal = if True, will raise ParseFatalException to stop parsing immediately; otherwise will raise ParseException
+
     """
     msg = message if message is not None else "failed user-defined condition"
     exc_type = ParseFatalException if fatal else ParseException
@@ -434,6 +436,7 @@ class ParserElement:
         expression are cleared.
 
         Optional keyword arguments:
+
         - callDuringTry = (default= ``False``) indicate if parse action should be run during lookaheads and alternate testing
 
         Note: the default parsing behavior is to expand tabs in the input string
@@ -483,6 +486,7 @@ class ParserElement:
         functions passed to ``addCondition`` need to return boolean success/fail of the condition.
 
         Optional keyword arguments:
+
         - message = define a custom message to be used in the raised exception
         - fatal = if True, will raise ParseFatalException to stop parsing immediately; otherwise will raise
           ParseException
@@ -513,10 +517,12 @@ class ParserElement:
         """Define action to perform if parsing fails at this expression.
            Fail acton fn is a callable function that takes the arguments
            ``fn(s, loc, expr, err)`` where:
+
            - s = string being parsed
            - loc = location where expression match was attempted and failed
            - expr = the parse expression that failed
            - err = the exception thrown
+
            The function returns no value.  It may throw :class:`ParseFatalException`
            if it is desired to stop parsing immediately."""
         self.failAction = fn
@@ -754,7 +760,7 @@ class ParserElement:
         :returns: the parsed data as a :class:`ParseResults` object, which may be accessed as a `list`, a `dict`, or
           an object with attributes if the given parser includes results names.
 
-        If the input string is required to match the entire grammar, ``parseAll`` flag must be set to True. This
+        If the input string is required to match the entire grammar, ``parseAll`` flag must be set to ``True``. This
         is also equivalent to ending the grammar with ``StringEnd()``.
 
         To report proper column numbers, ``parseString`` operates on a copy of the input string where all tabs are
@@ -1371,10 +1377,12 @@ class ParserElement:
         Example::
 
             patt = OneOrMore(Word(alphas))
-            patt.parseString('ablaj /* comment */ lskjd') # -> ['ablaj']
+            patt.parseString('ablaj /* comment */ lskjd')
+            # -> ['ablaj']
 
             patt.ignore(cStyleComment)
-            patt.parseString('ablaj /* comment */ lskjd') # -> ['ablaj', 'lskjd']
+            patt.parseString('ablaj /* comment */ lskjd')
+            # -> ['ablaj', 'lskjd']
         """
         if isinstance(other, str_type):
             other = Suppress(other)
@@ -1544,15 +1552,15 @@ class ParserElement:
          - tests - a list of separate test strings, or a multiline string of test strings
          - parseAll - (default= ``True``) - flag to pass to :class:`parseString` when running tests
          - comment - (default= ``'#'``) - expression for indicating embedded comments in the test
-              string; pass None to disable comment filtering
+           string; pass None to disable comment filtering
          - fullDump - (default= ``True``) - dump results as list followed by results names in nested outline;
-              if False, only dump nested list
+           if False, only dump nested list
          - printResults - (default= ``True``) prints test output to stdout
          - failureTests - (default= ``False``) indicates if these tests are expected to fail parsing
          - postParse - (default= ``None``) optional callback for successful parse results; called as
-              `fn(test_string, parse_results)` and returns a string to be added to the test output
+           `fn(test_string, parse_results)` and returns a string to be added to the test output
          - file - (default= ``None``) optional file-like object to which test output will be written;
-              if None, will default to ``sys.stdout``
+           if None, will default to ``sys.stdout``
 
         Returns: a (success, results) tuple, where success indicates that all tests succeeded
         (or failed if ``failureTests`` is True), and the results contain a list of lines of each
@@ -1626,7 +1634,7 @@ class ParserElement:
 
             expr.runTest(r"this is a test\\n of strings that spans \\n 3 lines")
 
-        (Note that this is a raw string literal, you must include the leading 'r'.)
+        (Note that this is a raw string literal, you must include the leading ``'r'``.)
         """
         if isinstance(tests, str_type):
             tests = list(map(type(tests).strip, tests.rstrip().splitlines()))
@@ -1926,7 +1934,8 @@ class CaselessLiteral(Literal):
 
     Example::
 
-        OneOrMore(CaselessLiteral("CMD")).parseString("cmd CMD Cmd10") # -> ['CMD', 'CMD', 'CMD']
+        OneOrMore(CaselessLiteral("CMD")).parseString("cmd CMD Cmd10")
+        # -> ['CMD', 'CMD', 'CMD']
 
     (Contrast with example for :class:`CaselessKeyword`.)
     """
@@ -1950,7 +1959,8 @@ class CaselessKeyword(Keyword):
 
     Example::
 
-        OneOrMore(CaselessKeyword("CMD")).parseString("cmd CMD Cmd10") # -> ['CMD', 'CMD']
+        OneOrMore(CaselessKeyword("CMD")).parseString("cmd CMD Cmd10")
+        # -> ['CMD', 'CMD']
 
     (Contrast with example for :class:`CaselessLiteral`.)
     """
@@ -2048,7 +2058,7 @@ class Word(Token):
     two characters, for instance.
 
     :class:`srange` is useful for defining custom character set strings
-    for defining ``Word`` expressions, using range notation from
+    for defining :class:`Word` expressions, using range notation from
     regular expression character sets.
 
     A common mistake is to use :class:`Word` to match a specific literal
@@ -2253,7 +2263,7 @@ class Regex(Token):
     expression. Defined with string specifying the regular expression in
     a form recognized by the stdlib Python  `re module <https://docs.python.org/3/library/re.html>`_.
     If the given regex contains named groups (defined using ``(?P<name>...)``),
-    these will be preserved as named parse results.
+    these will be preserved as named :class:`ParseResults`.
 
     If instead of the Python stdlib re module you wish to use a different RE module
     (such as the `regex` module), you can replace it by either building your
@@ -2379,7 +2389,7 @@ class Regex(Token):
 
     def sub(self, repl):
         r"""
-        Return Regex with an attached parse action to transform the parsed
+        Return :class:`Regex` with an attached parse action to transform the parsed
         result as if called using `re.sub(expr, repl, string) <https://docs.python.org/3/library/re.html#re.sub>`_.
 
         Example::
@@ -2892,9 +2902,9 @@ class StringEnd(_PositionToken):
 
 
 class WordStart(_PositionToken):
-    """Matches if the current position is at the beginning of a Word,
-    and is not preceded by any character in a given set of
-    ``wordChars`` (default= ``printables``). To emulate the
+    """Matches if the current position is at the beginning of a
+    :class:`Word`, and is not preceded by any character in a given
+    set of ``wordChars`` (default= ``printables``). To emulate the
     ``\b`` behavior of regular expressions, use
     ``WordStart(alphanums)``. ``WordStart`` will also match at
     the beginning of the string being parsed, or at the beginning of
@@ -2917,8 +2927,8 @@ class WordStart(_PositionToken):
 
 
 class WordEnd(_PositionToken):
-    """Matches if the current position is at the end of a Word, and is
-    not followed by any character in a given set of ``wordChars``
+    """Matches if the current position is at the end of a :class:`Word`,
+    and is not followed by any character in a given set of ``wordChars``
     (default= ``printables``). To emulate the ``\b`` behavior of
     regular expressions, use ``WordEnd(alphanums)``. ``WordEnd``
     will also match at the end of the string being parsed, or at the end
@@ -3077,7 +3087,7 @@ class ParseExpression(ParserElement):
 
 class And(ParseExpression):
     """
-    Requires all given :class:`ParseExpression` s to be found in the given order.
+    Requires all given :class:`ParseExpression`\ s to be found in the given order.
     Expressions may be separated by whitespace.
     May be constructed using the ``'+'`` operator.
     May also be constructed using the ``'-'`` operator, which will
@@ -3453,7 +3463,7 @@ class MatchFirst(ParseExpression):
 
 
 class Each(ParseExpression):
-    """Requires all given :class:`ParseExpression` s to be found, but in
+    """Requires all given :class:`ParseExpression`\ s to be found, but in
     any order. Expressions may be separated by whitespace.
 
     May be constructed using the ``'&'`` operator.
@@ -3756,10 +3766,11 @@ class PrecededBy(ParseElementEnhance):
      - retreat - (default= ``None``) - (int) maximum number of characters
        to lookbehind prior to the current parse location
 
-    If the lookbehind expression is a string, Literal, Keyword, or
-    a Word or CharsNotIn with a specified exact or maximum length, then
-    the retreat parameter is not required. Otherwise, retreat must be
-    specified to give a maximum number of characters to look back from
+    If the lookbehind expression is a string, :class:`Literal`,
+    :class:`Keyword`, or a :class:`Word` or :class:`CharsNotIn`
+    with a specified exact or maximum length, then the retreat
+    parameter is not required. Otherwise, retreat must be specified to
+    give a maximum number of characters to look back from
     the current parse position for a lookbehind match.
 
     Example::
@@ -3825,7 +3836,7 @@ class NotAny(ParseElementEnhance):
     input string, it only verifies that the specified parse expression
     does *not* match at the current position.  Also, ``NotAny`` does
     *not* skip over leading whitespace. ``NotAny`` always returns
-    a null token list.  May be constructed using the '~' operator.
+    a null token list.  May be constructed using the ``'~'`` operator.
 
     Example::
 
@@ -3971,8 +3982,8 @@ class ZeroOrMore(_MultipleMatch):
     Parameters:
      - expr - expression that must match zero or more times
      - stopOn - (default= ``None``) - expression for a terminating sentinel
-          (only required if the sentinel would ordinarily match the repetition
-          expression)
+       (only required if the sentinel would ordinarily match the repetition
+       expression)
 
     Example: similar to :class:`OneOrMore`
     """
@@ -4082,12 +4093,12 @@ class SkipTo(ParseElementEnhance):
     Parameters:
      - expr - target expression marking the end of the data to be skipped
      - include - (default= ``False``) if True, the target expression is also parsed
-          (the skipped text and target expression are returned as a 2-element list).
+       (the skipped text and target expression are returned as a 2-element list).
      - ignore - (default= ``None``) used to define grammars (typically quoted strings and
-          comments) that might contain false matches to the target expression
+       comments) that might contain false matches to the target expression
      - failOn - (default= ``None``) define expressions that are not allowed to be
-          included in the skipped test; if found before the target expression is found,
-          the SkipTo is not a match
+       included in the skipped test; if found before the target expression is found,
+       the SkipTo is not a match
 
     Example::
 
@@ -4203,12 +4214,12 @@ class Forward(ParseElementEnhance):
     """Forward declaration of an expression to be defined later -
     used for recursive grammars, such as algebraic infix notation.
     When the expression is known, it is assigned to the ``Forward``
-    variable using the '<<' operator.
+    variable using the ``'<<'`` operator.
 
     Note: take care when assigning to ``Forward`` not to overlook
     precedence of operators.
 
-    Specifically, '|' has a lower precedence than '<<', so that::
+    Specifically, ``'|'`` has a lower precedence than ``'<<'``, so that::
 
         fwdExpr << a | b | c
 
@@ -4221,7 +4232,7 @@ class Forward(ParseElementEnhance):
 
         fwdExpr << (a | b | c)
 
-    Converting to use the '<<=' operator instead will avoid this problem.
+    Converting to use the ``'<<='`` operator instead will avoid this problem.
 
     See :class:`ParseResults.pprint` for an example of a recursive
     parser created using ``Forward``.
@@ -4396,10 +4407,12 @@ class Group(TokenConverter):
         num = Word(nums)
         term = ident | num
         func = ident + Optional(delimitedList(term))
-        print(func.parseString("fn a, b, 100"))  # -> ['fn', 'a', 'b', '100']
+        print(func.parseString("fn a, b, 100"))
+        # -> ['fn', 'a', 'b', '100']
 
         func = ident + Group(Optional(delimitedList(term)))
-        print(func.parseString("fn a, b, 100"))  # -> ['fn', ['a', 'b', '100']]
+        print(func.parseString("fn a, b, 100"))
+        # -> ['fn', ['a', 'b', '100']]
     """
 
     def __init__(self, expr):
@@ -4609,7 +4622,7 @@ _reBracketExpr = (
 
 
 def srange(s):
-    r"""Helper to easily define string ranges for use in Word
+    r"""Helper to easily define string ranges for use in :class:`Word`
     construction. Borrows syntax from regexp '[]' string range
     definitions::
 
diff --git a/pyparsing/helpers.py b/pyparsing/helpers.py
index 5408885..a7ca83d 100644
--- a/pyparsing/helpers.py
+++ b/pyparsing/helpers.py
@@ -135,8 +135,8 @@ def matchPreviousExpr(expr):
 
 
 def oneOf(strs, caseless=False, useRegex=True, asKeyword=False):
-    """Helper to quickly define a set of alternative Literals, and makes
-    sure to do longest-first testing when there is a conflict,
+    """Helper to quickly define a set of alternative :class:`Literal`\ s,
+    and makes sure to do longest-first testing when there is a conflict,
     regardless of the input order, but returns
     a :class:`MatchFirst` for best performance.
 
@@ -147,10 +147,10 @@ def oneOf(strs, caseless=False, useRegex=True, asKeyword=False):
      - caseless - (default= ``False``) - treat all literals as
        caseless
      - useRegex - (default= ``True``) - as an optimization, will
-       generate a Regex object; otherwise, will generate
+       generate a :class:`Regex` object; otherwise, will generate
        a :class:`MatchFirst` object (if ``caseless=True`` or ``asKeyword=True``, or if
        creating a :class:`Regex` raises an exception)
-     - asKeyword - (default= ``False``) - enforce Keyword-style matching on the
+     - asKeyword - (default= ``False``) - enforce :class:`Keyword`-style matching on the
        generated expressions
 
     Example::
diff --git a/pyparsing/testing.py b/pyparsing/testing.py
index 756d500..d924793 100644
--- a/pyparsing/testing.py
+++ b/pyparsing/testing.py
@@ -25,7 +25,8 @@ class pyparsing_test:
          - literal string auto-conversion class
          - __diag__ settings
 
-        Example:
+        Example::
+
             with reset_pyparsing_context():
                 # test that literals used to construct a grammar are automatically suppressed
                 ParserElement.inlineLiteralsUsing(Suppress)
@@ -92,8 +93,8 @@ class pyparsing_test:
             self, result, expected_list=None, expected_dict=None, msg=None
         ):
             """
-            Unit test assertion to compare a ParseResults object with an optional expected_list,
-            and compare any defined results names with an optional expected_dict.
+            Unit test assertion to compare a :class:`ParseResults` object with an optional ``expected_list``,
+            and compare any defined results names with an optional ``expected_dict``.
             """
             if expected_list is not None:
                 self.assertEqual(expected_list, result.asList(), msg=msg)
@@ -105,7 +106,7 @@ class pyparsing_test:
         ):
             """
             Convenience wrapper assert to test a parser element and input string, and assert that
-            the resulting ParseResults.asList() is equal to the expected_list.
+            the resulting ``ParseResults.asList()`` is equal to the ``expected_list``.
             """
             result = expr.parseString(test_string, parseAll=True)
             if verbose:
@@ -117,7 +118,7 @@ class pyparsing_test:
         ):
             """
             Convenience wrapper assert to test a parser element and input string, and assert that
-            the resulting ParseResults.asDict() is equal to the expected_dict.
+            the resulting ``ParseResults.asDict()`` is equal to the ``expected_dict``.
             """
             result = expr.parseString(test_string, parseAll=True)
             if verbose:
@@ -128,10 +129,10 @@ class pyparsing_test:
             self, run_tests_report, expected_parse_results=None, msg=None
         ):
             """
-            Unit test assertion to evaluate output of ParserElement.runTests(). If a list of
-            list-dict tuples is given as the expected_parse_results argument, then these are zipped
-            with the report tuples returned by runTests and evaluated using assertParseResultsEquals.
-            Finally, asserts that the overall runTests() success value is True.
+            Unit test assertion to evaluate output of ``ParserElement.runTests()``. If a list of
+            list-dict tuples is given as the ``expected_parse_results`` argument, then these are zipped
+            with the report tuples returned by ``runTests`` and evaluated using ``assertParseResultsEquals``.
+            Finally, asserts that the overall ``runTests()`` success value is ``True``.
 
             :param run_tests_report: tuple(bool, [tuple(str, ParseResults or Exception)]) returned from runTests
             :param expected_parse_results (optional): [tuple(str, list, dict, Exception)]
diff --git a/pyparsing/util.py b/pyparsing/util.py
index 0992075..a80a6d3 100644
--- a/pyparsing/util.py
+++ b/pyparsing/util.py
@@ -43,7 +43,7 @@ def col(loc, strg):
    Note: the default parsing behavior is to expand tabs in the input string
    before starting the parsing process.  See
    :class:`ParserElement.parseString` for more
-   information on parsing strings containing ``<TAB>`` s, and suggested
+   information on parsing strings containing ``<TAB>``\ s, and suggested
    methods to maintain a consistent view of the parsed string, the parse
    location, and line and column positions within the parsed string.
    """
@@ -57,7 +57,7 @@ def lineno(loc, strg):
 
     Note - the default parsing behavior is to expand tabs in the input string
     before starting the parsing process.  See :class:`ParserElement.parseString`
-    for more information on parsing strings containing ``<TAB>`` s, and
+    for more information on parsing strings containing ``<TAB>``\ s, and
     suggested methods to maintain a consistent view of the parsed string, the
     parse location, and line and column positions within the parsed string.
     """