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.

Thunell

I think you can write your own help(). It's not so difficult as may seem; just some inspect code and launching the pager. Really wouldn't be hard. – Bean

Making it easier to customise help() (e.g. by exposing more functionality in the pydoc module) would make a good feature request on bugs.python.org – Platt

This existing question may also be of interest: #1193132 (Not exactly the same thing, but related enough to be relevant) – Platt

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.

Eupatorium