restructuredText、文档字符串和Python交互式命令行

Question

我正在使用reStructuredText来给我的代码写文档，这样可以通过epydoc生成漂亮的离线HTML页面。

效果非常好。唯一的问题是，当我在Python的交互式命令行中使用help()函数时，它并不能解析文档字符串中的reST元数据，而是直接显示原文。

有没有办法让help()函数对文档字符串进行一些简单的处理呢？

我并不指望它能显示斜体字或超链接，但至少希望能做一些基本的清理，以提高可读性。

Answer 1

help()这个函数是由site模块添加到内置命名空间中的。你可以通过在你的路径中创建一个sitecustomize.py模块来进行自定义（通常这个文件会放在site-packages文件夹里）。

然后在sitecustomize.py文件里，你可以添加你想要的任何自定义内容。

你可以用几种方式来处理这个问题：

如果你想改变help()函数本身的（表面上看起来的）行为，可以用一个装饰器来包装这个help函数，像这样：

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

我个人更倾向于一种稍微不同的解决方案，因为你无法预测你的清理函数会对那些不是用重构文本写的help输出做什么。

所以我会创建一个包装函数：

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

这样的话，如果你需要的话，仍然可以访问原始的help()函数。

注意：在sitecustomize.py中做任何事情时要小心，因为你在这里做的任何更改可能会影响你整个解释器会话（以及每一个解释器会话），这有时会导致意想不到的后果。