PyXR 0.9.4.13 Readme file

Introduction

PyXR generates pretty-printed HTML from python source files. The generated web pages have extensive cross-referencing hyperlinks.

New Features for Release 0.9.4.13 (01 Jan 2005 14:46:44 +0000)

Support for new language features in 2.4.
Fixes for new html documentation formatting.
Improved handling of modules with extended html docs (such as the os module)
Proper handling of nonexistant entries in sys.path such as c:\python23\lib\plat-win
Proper handling of mixed tabs and spaces
Proper display of line continuations via \
Use universal newline mode when reading .py source files (if supported)
Append to releases.py in binary mode so that it uses proper newlines.
User-configurable headers and footers on pages
More detailed documentation of the settings.cfg configuation file included in settings.html
Added filenames to exception text for fatal errors due to malformed python source.
SkipInvalidFIles flag defaults to 1 now. Must turn off to debug.

Basic Installation

PyXR can be downloaded here.
A PyXR'ed version of python 2.4's source can be viewed here.
Unzip the archive, copy to your site-packages directory
Create a settings.cfg file in the PyXR directory. Several sample configurations exist. You might be able to rename the one for your os to settings.cfg. More detailed configuration instructions are available in the file 'settings.html' in the PyXR distribution.

Using PyXR

Trying out the app

PyXR was designed to generate static html pages that are in turn served up by your platform's webserver (IIS, apache, etc). However, there is a testbed server that you can use if you want to try PyXR before generating serveral megs of output. Simply run "python webserver.py" from the PyXR directory. This will perform initialization of the index (which will take a few minutes) and start a webserver at http://localhost:8088/ that will server 100 pages. This builds the webpages without any caching, so it'll take a few seconds to generate each page as you're browsing.

Generating Static pages

If you've tested the app, and decided that you like it, you'll probably want to generate static output. To do so, just run 'python buildWeb.py' from the PyXR directory. [You may want to review the settings configuration section before doing this]. Ten to twenty minutes later, you should have a full copy of the source on your server. Scheduling a nightly automated job is left as an exercise for the reader.

Integrating the Library Reference

Library Reference isn't integrated by default because the .html documents can exist in a variety of locations on any given platform.

You may need to download the archive (2.4 is here) from python.org or "make" the documentation manually.
You'll probably want to extract the archive into a webserver's directory (\inetpub\wwwroot\, /var/www/htdocs, etc) and verify that you can navigate. (IIS doesn't use index.html as a default directory page until you set it up.)

Once you have the documentation installed, set useLibraryReference to 1 in settings.cfg and set the libUrl and libDirectory appropriately. These should point to the 'lib' subdirectory and not the 'doc' directory. Example:

[libraryReference]
useLibraryReference = 1
libDirectory = c:\inetpub\wwwroot\python23doc\lib\
libUrl = /python23doc/lib/

Generating a cached data file

Either of the above options has an initialization phase that can take serveral minutes. They can accept an optional parameter that points to a cached data file. This will speed things up in development (or if for some reason you just can't run buildWeb.py due to capacity issues). Running "python astProcess.py filename" will generate the file. After it's been generated, "python webserver.py filename" or "python buildWeb.py filename" will utilize it. Just remember not to edit any of your .py files if you're doing this ;)

ToDo- the future

Figure out how to handle superclasses. I don't think hyperlinking directly to another class in another file would be intuitive. There should be something we can do though.
Refactor, refactor, refactor
Performance, performance, performance

Not ToDo (so don't ask)

Won't try to tie into CVS versions. You'd need to know the state of every referenced document for a particular version.
Won't try to implement incremental updates or caching. It's more difficult than just checking a file's timestamp. Use a scheduled job instead.

Questions? Comments? Critisisms?

logistix at users.sourceforge.net