[Doc-SIG] htmldoc.py and inspect.py

[will]

If you change the arg-reading code in htmldoc.py to something along
these lines, then you can do ool documentation on modules that import
modules in other (non-standard) directories.

if __name__ == "__main__":
    import os
    modnames = []
    argn = 1
    while argn < len(sys.argv):
        arg = sys.argv[argn]
        if arg == "-m":
            sys.path.append(sys.argv[argn + 1])
            argn = argn + 1
        elif os.path.isdir(arg):
            for file in os.listdir(arg):
                if file[-3:] == ".py":
                    modnames.append(file[:-3])
                elif file[-9:] == "module.so":
                    modnames.append(file[:-9])
        else:
            if arg[-3:] == ".py":
                modnames.append(arg[:-3])
            else:
                modnames.append(arg)
        argn = argn + 1

I'm looking into building a function to generate a toc as well.  So if
you call:

   htmldoc.py -m /mud/server/ /mud/server/*.py

then it will build a toc with all the py files in /mud/server/.  Maybe
have a command-line flag to toggle whether or not to generate a toc
and what to call it.

I'm impressed though.  So far it's been very easy to use.  Took me
about 10 minutes to get it working with our project which right now
spans a few directories and consists of almost a hundred different
modules.

Also, I really like that it uses &nbsp; and <br> instead of <p>.  This
keeps the outputted html looking exactly like the doc-string did.
Makes it easier to build ascii diagrams and such.

I like that it doesn't use XML as a semantic mark-up.  Whoever (I
deleted the email--sorry bout that) mentioned that should refer to the
archives on lengthy discussion on the topic of what to use for markup
and see if that covers their arguments for/against using XML in this
fashion.

So, in my opinion, apart from a few minor changes:
 - needs to be able to add other dirs to sys.path for importing
purposes
 - needs to generate a toc for files it's documenting
 - needs to generate an index of functions/classes/modules
 - maybe a few other flags to toggle some of the things folks dislike
   like including __blah__ type functions

Other than that, it's great!  Thank you muchly Ping!
/will

> -----Original Message-----
> From: doc-sig-admin@python.org [mailto:doc-sig-admin@python.org]On
> Behalf Of Ka-Ping Yee
> Sent: Tuesday, May 30, 2000 5:44 AM
> To: doc-sig@python.org; fdrake@acm.org
> Subject: [Doc-SIG] htmldoc.py and inspect.py
>
>
> Hi everyone.
>
> I'm writing to announce that i've posted my current work on
> a documentation generator.  Those of you who were in the
> doc-sig room at IPC8 may remember the example i showed.  Quite
> a few people seemed to like it and i promised to produce the
> script -- so here i am trying to make good on my promise.
>
> Done:
>     - documentation of user modules, classes, methods, and functions
>     - documentation of built-in functions
>     - automatic hyperlinking when classes and methods are mentioned
>     - detection of leading comments when no docstring is present
>     - overview of class inheritance tree within a module
>     - generation of HTML files from the command line
>     - all generated files are SGML compliant! :) :) (HTML
> 4.0 Transitional)
>
> To do:
>     - no directory/package indexing yet
>     - simple HTTP server (so you can get fresh docs on your
> own modules)
>
> As there are still items on the to-do list it's not entirely
> done yet -- but there is enough done to work fairly well, and
> i wanted to give you a chance to look at it and let me know
> what you think.
>
> The modules are:
>
>     http://www.lfw.org/python/htmldoc.py
>     http://www.lfw.org/python/inspect.py
>
> Fred: i would like to seriously propose this to go with 1.6.
> Will you consider it?
>
> The "htmldoc" module is actually quite small (only about 300
> lines) as most of the hard work has been factored out into
> the "inspect" module -- a non-HTML-specific collection of
> routines for getting all kinds of information out of your
> Python objects.  My favourite routine in "inspect" is
> inspect.getsource(object), which can get you the source code
> for a function, method, or class.
>
> The IPC8 example i showed is at
>
>     http://www.lfw.org/python/SocketServer.html
>
> That output was produced by a script called "manpy.cgi" that
> i wrote at work, and unfortunately that meant the script could
> not be distributed outside of my company.  The new script
> produces very similar output, but it has been rewritten from
> scratch on my own time -- which means (a) it's completely
> unencumbered by any IP claims; and (b) i got to make it a
> little bit cleaner.
>
> I have run the new script over the Python 1.5.2 standard
> library.  Please browse the results at
>
>     http://www.lfw.org/python/htmldoc/
>
> I welcome your feedback!
>
> Thanks,
>
>
>
> -- ?!ng
>
> "To be human is to continually change.  Your desire to
> remain as you are
> is what ultimately limits you."
>     -- The Puppet Master, Ghost in the Shell
>
>
>
> _______________________________________________
> Doc-SIG maillist  -  Doc-SIG@python.org
> http://www.python.org/mailman/listinfo/doc-sig