This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Improve HTML documentation of a directory
Type: enhancement Stage: test needed
Components: Library (Lib) Versions: Python 3.10, Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: georg.brandl, noam, noamr, ping, ron_adam
Priority: low Keywords: patch

Created on 2004-06-25 11:29 by noamr, last changed 2022-04-11 14:56 by admin.

Files
File name Uploaded Description Edit
pydoc.py.betterdocdir.diff noamr, 2004-06-25 11:29 A context diff against pydoc.py 1.92
Messages (4)
msg46217 - (view) Author: Noam Raphael (noamr) * Date: 2004-06-25 11:29
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.
msg59300 - (view) Author: Christian Heimes (christian.heimes) * (Python committer) Date: 2008-01-05 18:21
What do you think about the feature, Georg?
msg59338 - (view) Author: Noam Yorav-Raphael (noam) Date: 2008-01-05 23:20
I just wanted to say that I'm not going to bother too much with this
right now - Personally I will just use epydoc when I want to create an
HTML documentation. Of course, you can still do whatever you like with
the patch.

Good luck,
Noam
msg59377 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2008-01-06 14:35
Unassigning myself - I have no opinion on pydoc.
History
Date User Action Args
2022-04-11 14:56:05adminsetgithub: 40448
2020-11-11 17:38:11iritkatrielsetversions: + Python 3.9, Python 3.10, - Python 3.2
2013-11-17 15:25:53christian.heimessetnosy: - christian.heimes
2010-08-19 15:03:45BreamoreBoysetnosy: + ron_adam

versions: + Python 3.2, - Python 2.7
2009-02-14 14:46:55ajaksu2setpriority: normal -> low
stage: test needed
versions: + Python 2.7, - Python 2.6
2008-01-06 14:35:52georg.brandlsetassignee: georg.brandl ->
messages: + msg59377
2008-01-05 23:20:08noamsetnosy: + noam
messages: + msg59338
2008-01-05 18:21:22christian.heimessetassignee: ping -> georg.brandl
type: enhancement
messages: + msg59300
nosy: + christian.heimes, georg.brandl
versions: + Python 2.6
2004-06-25 11:29:28noamrcreate