contenido repetitivo en docstrings

Question

¿Cuáles son buenas maneras de tratar con contenido repetitivo en las cadenas de documentación? Tengo muchas funciones que toman argumentos 'estándar', que tienen que ser explicado en la cadena de documentación, pero sería bueno para escribir las partes pertinentes de la cadena de documentación sólo una vez, ya que esto sería mucho más fácil de mantener y actualizar. Ingenuamente intentado lo siguiente:

arg_a = "a: a very common argument"

def test(a):
    '''
    Arguments:
    %s
    ''' % arg_a
    pass

Pero esto no funciona, porque cuando lo hago help(test) no veo la cadena de documentación. ¿Hay una buena manera de hacer esto?

Answer 1

Como dicen las otras respuestas, es necesario cambiar el miembro __doc__ del objeto función. Una buena manera de hacer esto es utilizar un decorador que llevará a cabo el formato de la cadena de documentación:

def fixdocstring(func):
    func.__doc__ = func.__doc__.replace('<arg_a>', 'a: a very common argument')
    #(This is just an example, other string formatting methods can be used as well.)
    return func

@fixdocstring
def test(a):
    '''
    Arguments:
    <arg_a>
    ''''
    pass

Answer 2

__doc__ es asignable en la mayoría de los tipos definidos por el usuario:

arg_a = "a: a very common argument"

def test(a):
    pass

test.__doc__ = '''
    Arguments:
    %s
    ''' % arg_a

Answer 3

No hay manera obvia de hacerlo por lo que yo sé (al menos no sin la reasignación explícitamente __doc__ como sugiere Ignacio).

Pero creo que esto sería una cosa terrible a hacer. Considere lo siguiente:

¿Qué pasa si estoy navegando a través de su código y la lectura de esta cadena de documentación en el 300-ésima línea de su archivo? ¿De verdad quieres que vaya buscar para el argumento?