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