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.

Start by examining the proposed behavior in pydoc_end_demo.py and how the pydoc and doctest entry points currently treat docstrings. Determine the intended interaction between the proposed marker and doctest cases, then add coverage showing that concise documentation remains visible while later examples remain testable.