Printing Docstrings Without Importing

Sun Jul 31 23:11:08 EDT 2005

On 30 Jul 2005 11:08:29 -0700, "Kamilche" <klachemin at comcast.net> wrote:

>I have a large project that is getting complex, and I would like to
>print the docstrings without importing the modules. The only Python
>utility I could find references is apparently defunct and hasn't been
>updated in 4 years.
>
>I don't care how spartan the output is - it could look exactly like
>python's internal docstrings, for all I care.  It would be a nice added
>bonus if it printed to HTML, but not if it greatly increased the
>interface complexity.  But I don't want to have to import the module to
>run it! I want to just have a function that I pass a list of filenames
>to.
>
>Does anyone know of such a utility?
>
No, but here's one I just created (not tested very much):

----< docstr2html.py >--------------------------------------------
# docstr2html.py
"""
Prints html to display docstrings of modules specified on command line,
with optional globbing and html page title default override.

  Usage: [python] docstr2html.py [-title "some title"] (file_pattern)+

Note: If redirecting stdout, some windows versions require [python] to be explicit.
"""
import glob, time, compiler

# copied from cgi module:
def escape(s, quote=None):
    """Replace special characters '&', '<' and '>' by SGML entities."""
    s = s.replace("&", "&") # Must be done first!
    s = s.replace("<", "<")
    s = s.replace(">", ">")
    if quote:
        s = s.replace('"', """)
    return s

def htmlhdr(title=None):
    if title is None: title = 'doc strings as of %s'%time.ctime()
    print '<html><head><title>%s</title></head><body>' %escape(title)

def htmltrlr():
    print '</body></html>'

def module_file_docstr2html(modulesourcepath):
    print '<br>'
    print '<table border="2">'
    print '    <tr bgcolor="#99FFFF"><th>%s</th></tr>' % escape(modulesourcepath)
    try:
        print '    <tr bgcolor="#99FF99"><td><pre>%s</pre></td></tr>' % escape(compiler.parseFile(modulesourcepath).doc)
    except Exception, e:
        print '    <tr bgcolor="#FFFFFF"><td><font color="#FF0000"><b>Error encountered:<br>%s</b></font></td></tr>' % escape(
            'Exception %s: %s' % (e.__class__.__name__, e))
    print '</table>'

if __name__ == '__main__':
    import sys, os
    args = sys.argv[1:]
    if not args: raise SystemExit(__doc__)
    if args[0] == '-title': args.pop(0); title = args.pop(0)
    else: title = None
    htmlhdr(title)
    for fspec in args:
        for path in glob.glob(fspec):
            module_file_docstr2html(os.path.abspath(path))
    htmltrlr()
------------------------------------------------------------------

Running it (first to get the help response, which is just the doc string ;-)

[20:04] C:\pywk\ut>python docstr2html.py

Prints html to display docstrings of modules specified on command line,
with optional globbing and html page title default override.

  Usage: [python] docstr2html.py [-title "some title"] (file_pattern)+

Note: If redirecting stdout, some windows versions require [python] to be explicit.

Then generating the html:

[20:04] C:\pywk\ut>python docstr2html.py docstr2html.py
<html><head><title>doc strings as of Sun Jul 31 20:04:55 2005</title></head><body>
<br>
<table border="2">
    <tr bgcolor="#99FFFF"><th>C:\pywk\ut\docstr2html.py</th></tr>
    <tr bgcolor="#99FF99"><td><pre>
Prints html to display docstrings of modules specified on command line,
with optional globbing and html page title default override.

  Usage: [python] docstr2html.py [-title "some title"] (file_pattern)+

Note: If redirecting stdout, some windows versions require [python] to be explicit.
</pre></td></tr>
</table>
</body></html>

You can use file specs like someplace\*.py (wild cards) and it should do all the files
and put it all in tables in the html output. Note that is uses all file specs as patterns,
and ignores without complaint any that don't match anything.

Regards,
Bengt Richter