[Patches] [ python-Patches-979658 ] Improve HTML documentation of a directory

[SourceForge.net]

Patches item #979658, was opened at 2004-06-25 14:29
Message generated for change (Tracker Item Submitted) made by Item Submitter
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=305470&aid=979658&group_id=5470

Category: Library (Lib)
Group: None
Status: Open
Resolution: None
Priority: 5
Submitted By: Noam Raphael (noamr)
Assigned to: Nobody/Anonymous (nobody)
Summary: Improve HTML documentation of a directory

Initial Comment:
Attached is a patch which improves pydoc's HTML
documentation of a complete directory. It consists of
two parts. The first gives adds functionality to the
"pydoc -w <dirname>" command, mostly in the spirit of
compileall.py. The second fixes a bug, which causes
pydoc to search for modules in sys.path instead of in
the actual directory documented.

pydoc -w <dirname> functionality
=========================
  Here's my actual situation: There's a package
maintainance system, where you first create files in
your home directory and then use the system to install
them in a common place. For example, if a package is
called foo, and includes the modules ya.py and
chsia.py, the modules will be named
/home/noam/foo/lib/python/{ya,chsia}.py. I want to
automatically document them, so that the HTML files
will sit in /home/noam/foo/doc. After installing the
package, the python modules will be copied to
/usr/local/lib/python/, and the documentation will be
copied to /usr/local/doc/foo.
  I want to be able to type one command to generate all
the documentation, but I don't want to waste time if I
only need the documentation re-generated for one
module. So I made "pydoc -w <dir>" produce
documentation only if the target file was modified
before the module was. (pydoc -w <filename> still
writes the documentation even if it seems up to date.)
  It is perfectly legitimate to write a HTML
documentation for a module by your own. So I made pydoc
never overwrite HTML files which weren't created by
pydoc. To accomplish this, I added the tag <meta
name="generator" content="pydoc"> to the head of all
HTML files produced
by pydoc. A warning is printed if a module was modified
after its manually created documentation was modified.
  I wanted to be able to run "pydoc -w" from any
directory, not just from /home/noam/foo/doc, so I added
an option "-o <dir>", to specify the output directory.
(If it isn't specified, the current directory is used.)
  I wanted the documentation to refer to the installed
file (/usr/local/lib/python/foo.py), not to the file in
my home directory. So I added an option "-d <destdir>",
to specify the directory in which the files will reside
after being installed.
  To summarise, the command which I should now run to
produce the documentation is
pydoc -w -o doc/ -d /usr/local/ lib/python/
(running it from /home/noam/foo).
  The -d and -o options are already available in
compileall.py, for exactly the same reasons, I think.
  None of this should cause backward compatibility issues.

Module loading
===========
  Currently, safeimport(), used by writedocs(), gets
only a module name, and imports it using __import__().
This means that when you document a complete directory,
you can only produce HTML documentation for modules
which are already installed, and that a documentation
for the wrong version of a module may be produced. I
changed safeimport() to get an optional list of
directories in which to look for the module/package, in
which case it uses imp.find_module and imp.load_module
instead of __import__. This means that when producing
documentation for a complete directory, the actual
files in the directory are used, not installed modules
of the same name.


----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=305470&aid=979658&group_id=5470