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.

まず pydoc_end_demo.py で提案されている動作と、pydoc および doctest のエントリポイントが現在どのように docstring を扱っているかを調べます。提案された マーカーと doctest ケースの意図された相互作用を確認し、そのうえで、簡潔なドキュメントが表示されたまま、後続の例も引き続きテスト可能であることを示すカバレッジを追加します。