pydoc output control for doctest cases

Feature or enhancement

#File: pydoc_end_demo.py
"""
I very much appreciate both the doctest and the pydoc features of python for small developement
tasks with minimum overhead.

A slight enhancement to pydoc as proposed in this example would further increase the usefulness.
"""

def rotated( sequence, distance=1 ):  # example to demonstrate the <pydoc-end> proposal
    """ Returns sequence rotated by distance number of elements.

    Examples:  # small number of test cases (to be included in the pydoc output) show the use of the function
        >>> rotated( ( "one", "two", "three", "four" ) )
        ('four', 'one', 'two', 'three')
        >>> rotated( [ 2, 3, 5, 7, 11, 13 ], 2 )
        [11, 13, 2, 3, 5, 7]
        >>> rotated( "abcdefgh", -3 )
        'defghabc'

    <pydoc-end>  # the proposed indicator string instructs pydoc to stop ouput here ((for this docstring))
    
    Doctests:    # exhaustive number of further test cases - not relevant for the api user
                 # but needed for test quality - without the proposal the test cases clutter the pydoc output
        >>> rotated( "abcde", 0 )
        'abcde'
        >>> rotated( "abcde", 5 )  # abs(distance) == len(sequence)
        'abcde'
        >>> rotated( "abcde", -5 )
        'abcde'
        
        >>> rotated( "abcde", 6 )  # abs(distance) > len(sequence)
        'eabcd'
        >>> rotated( "abcde", -6 )
        'bcdea'
        
        >>> rotated( "", 5 )  # empty sequence
        ''
        >>> rotated( [], -3 )
        []
    """
    length = len(sequence)
    if length == 0: return sequence
    dist = distance % length
    return sequence[-dist:] + sequence[:-dist]


if __name__ == "__main__":

   # run the doctest cases:
   print( ">>> doctest >>>" )
   import doctest
   doctest.testmod()
   print( "<<< doctest <<<" )

Pitch

extensive doctest cases will no more clutter pydoc output: A single source file is sufficient for concise user docu as well as for comprehensive doctest cases.

Bắt đầu bằng việc kiểm tra hành vi được đề xuất trong pydoc_end_demo.py và cách các entry point của pydoc và doctest hiện xử lý docstring. Xác định tương tác dự kiến giữa marker được đề xuất và các trường hợp doctest, sau đó bổ sung coverage cho thấy tài liệu ngắn gọn vẫn hiển thị trong khi các ví dụ phía sau vẫn có thể được kiểm thử.