Search code examples
pythonrestructuredtextpydocepydoc

restructuredText, docstring and python interactive shell


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.


Solution

  • 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.