restructuredText, docstring and python interactive shell

Question

I am using reStructuredText to document my code, so as to get nice offline HTML pages by means of epydoc.

Results are brilliant. The only drawback is that when I use the Python interactive shell, the help() function does not parse the reST metadata in the documentation strings, and instead it displays the whole thing as it is.

Is there a way to have help() to do some minimal parsing of the docstrings?

I don't expect rendering of italic fonts or hyperlinks, but at least some minimal cleanup to increase readbility.

Answer 1

The help() function gets added to the builtin namespace by the site module, which you can customize by creating a sitecustomize.py module somewhere on your path (apparently it's usually kept in site-packages).

Then in the sitecustomize.py file you add whatever customizations you want.

You could handle this a couple of ways:

If you want to change the (apparent) behavior of the help() function itself, wrap the help function in a decorator, something like:

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

I would personally prefer a slightly different solution, because there's no telling what your cleanup function will do to help output that isn't written in RestructuredText.

So I would just create a wrapper function:

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

This way you still have access to the original help() function if you need it.

CAVEAT: be cautious when doing things in sitecustomize.py, as whatever you do here will likely affect your entire interpreter session (and every interpreter session), which can sometimes lead to unintended consequences.