restructuredText, docstring y python interactive shell

Question

Estoy usando reStructuredText para documentar mi código, a fin de obtener buenas páginas HTML fuera de línea mediante epydoc.

Los resultados son brillantes. El único inconveniente es que cuando uso el shell interactivo Python, la función help() no analiza los metadatos reST en las cadenas de documentación, y en su lugar muestra todo tal como está.

¿Hay alguna manera de tener ayuda() para realizar un análisis mínimo de las cadenas de documentos?

No espero la reproducción de fuentes o hipervínculos en cursiva, pero al menos una limpieza mínima para aumentar la capacidad de lectura.

Answer 1

La función help() se agrega al espacio de nombres incorporado por el módulo de site, que se puede personalizar mediante la creación de un módulo de sitecustomize.py algún lugar de su trayectoria (al parecer se mantiene habitualmente en site-packages).

Luego, en el archivo sitecustomize.py, agrega las personalizaciones que desee.

Se podía manejar esto un par de maneras:

Si desea cambiar el comportamiento (aparente) de la función help() sí, envolver la función de ayuda de un decorador, algo así como:

def help_wrapper(func): 
    def inner(*args): 
     results = func(*args) 
     return your_cleanup_function_here(results) 
help = help_wrapper(help) 

Yo personalmente preferiría una solución ligeramente diferente, porque no hay forma de saber qué hará su función de limpieza para ayudar a que no esté escrito en RestructuredText.

así que sólo crear una función de contenedor:

def my_help(*args): 
    return your_cleanup_function_here(help(*args)) 

De esta manera usted todavía tiene acceso a la función original help() si lo necesita.

advertencia: tenga cuidado al hacer las cosas en sitecustomize.py, como todo lo que hacemos aquí es probable que afecten toda la sesión intérprete (y cada sesión intérprete), que a veces puede conducir a consecuencias no deseadas.