sleepermud/lib/pymodules/doc.py

"""
doc.py

This module allows documentation for Python classes and modules to be viewed
in-game via the 'doc' command. 
"""
import pydoc, os, mudsys, display



################################################################################
# local variables
################################################################################

# where do we store documentation?
HTML_DOC_DIR = "../html/pydocs"

shortcuts = { "ch"      : "char",
              "sock"    : "mudsock",
              }

# just a list of all our builtin modules
builtins = [
    "char",
    "room",
    "obj",
    "exit",
    "account",
    "mudsock",
    "mud",
    "mudsys",
    "hooks",
    "event",
    "auxiliary",
    "storage",
    "olc",
    ]

# append all of our builtins to suggested reading list
suggested_reading = [mod for mod in builtins]

def register_module_doc(modname, package = None, root = "pymodules"):
    """Add a new module name to suggested_reading. If modname is a package,
       recursively add its packages as well
    """
    fname = root + "/" + modname.replace(".", "/")
    suggested_reading.append(modname)
    if os.path.isdir(fname):
        for file in os.listdir(fname):
            if (file.endswith(".py") or not "." in file) and not file[0] in "._":
                module = modname + "." + file.split(".", 1)[0]
                register_module_doc(module, root)
 
# now, append all of our Python packages and modules
for fname in os.listdir("pymodules/"):
    # look for modules and packages
    if (fname.endswith(".py") or not "." in fname) and not fname[0] in "._":
        modname = fname.split(".", 1)[0]
        register_module_doc(modname)



################################################################################
# player commands
################################################################################
def cmd_htmldoc(ch, cmd, arg):
    """Creates html documentation for all registered modules. html files will
       be saved to html/pydocs/
    """
    try:
        os.makedirs(HTML_DOC_DIR)
    except: pass
    doc = pydoc.HTMLDoc()
    for modname in suggested_reading:
        todoc = pydoc.locate(modname)
        if todoc != None:
            fname = HTML_DOC_DIR + "/" + modname + ".html"
            fl    = file(fname, "w+")
            fl.write(doc.page(modname, doc.document(todoc)))
            fl.close()

    builtin_index = doc.multicolumn([doc.modulelink(pydoc.locate(modname)) for modname in builtins], lambda x: x)
    
    # build our index page. That includes things in pymodules/ and builtins
    index_contents ="".join([doc.section("<big><strong>builtins</big></strong>",
                                         'white', '#ee77aa', builtin_index),
                             doc.index("../lib/pymodules/")])

    # go over all of our builtins and add them to the index
    index = file(HTML_DOC_DIR + "/index.html", "w+")
    index.write(doc.page("index", index_contents))
    index.close()
    
    ch.send("html documentation generated for all known modules.")

def cmd_doc(ch, cmd, arg):
    """Return Python documentation for the specified module, class, function,
       etc... for example:
       
       > doc char.Char

       Will return all available documentation for the Char class.
    """
    if arg == "":
        ch.page("\r\n".join(display.pagedlist({ "Topics" : suggested_reading },
                                              header = "Suggested doc readings include:")))
    else:
        # just because sometimes I forget periods
        arg = arg.replace(" ", ".")

        # are we looking for a shortcut value?
        if arg in shortcuts:
            arg = shortcuts[arg]

        # try to find what we're documenting
        todoc = pydoc.locate(arg)
        if todoc == None:
            ch.send("Could not find Python documentation on: '%s'" % arg)
        else:
            doc = pydoc.TextDoc()
            ch.page(doc.document(todoc).replace("{", "{{"))



################################################################################
# initialization
################################################################################
mudsys.add_cmd("doc",     None, cmd_doc,     "wizard", False)
mudsys.add_cmd("htmldoc", None, cmd_htmldoc, "admin",  False)