restructuredText, docstring и python интерактивная оболочка

Question

Я использую reStructuredText для документирования своего кода, чтобы получить красивые офлайн-страницы HTML с помощью epydoc.

Результаты блестящие. Единственным недостатком является то, что когда я использую интерактивную оболочку Python, функция help() не анализирует метаданные reST в строках документации, а вместо этого отображает все как есть.

Есть ли способ использовать help() для минимального анализа строк документации?

Я не ожидаю рендеринга курсивных шрифтов или гиперссылок, но хотя бы минимальная очистка для повышения читабельности.

Answer 1

help() функция добавляется во встроенное пространство имен site модуль, который вы можете настроить, создав sitecustomize.py модуль где-то на вашем пути (по-видимому, он обычно хранится в пакетах сайта).

Тогда в sitecustomize.py файл, который вы добавляете любые настройки, которые вы хотите.

Вы можете справиться с этим несколькими способами:

Если вы хотите изменить (кажущееся) поведение help() саму функцию, оберните функцию справки в декораторе, что-то вроде:

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

Лично я предпочел бы немного другое решение, потому что неясно, что будет делать ваша функция очистки, чтобы помочь выводу, который не записан в RestructuredText.

Поэтому я бы просто создал функцию-обертку:

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

Таким образом, у вас все еще есть доступ к оригиналу help() функционировать, если вам это нужно.

ПРЕДУПРЕЖДЕНИЕ: будьте осторожны при выполнении действий в sitecustomize.py, поскольку все, что вы здесь делаете, может повлиять на весь сеанс интерпретатора (и каждый сеанс интерпретатора), что иногда может привести к непредвиденным последствиям.