Formatting Python docstrings for readability when printed

Question

I've just started getting into adding docstrings to my classes/methods and I'm having difficulty in formatting them such that they are easily readable when printed. Some of the lines within the docstrings are long enough to wrap around on my IDE, and when I print the docstring in the console there are large gaps of whitespace in these breaks. Additionally, I would like to maintain a consistent indent scheme throughout the docstring, but these linebreaks violate it by forcing lines to print with not indent.

Are there certain best practices to docstring writing that I'm ignoring? Are there ways to print large strings such that formatting is respected?

Hope this makes sense, thanks.

Answer 1

Normally you use the help utility for viewing docstrings, it deals with inconsistency in whitespace:

>>> def test():
    """ first line
    HELLO THERE@
       ME TOO
    DOC STRING HERE
    """
    return 1

>>> help(test)
Help on function test in module __main__:

test()
    first line
    HELLO THERE@
       ME TOO
    DOC STRING HERE

>>> def test2():
    """
DOC string
text here"""
    return 5

>>> help(test2)
Help on function test2 in module __main__:

test2()
    DOC string
    text here

So while you can refer to PEP 8 for usual conventions, you can also just decide what format you like and just try to be consistent within your application.