Package Distribution Structure and HTML Documentation Template

General

This page describes the distribution structure and HTML documentation templates for Python packages developed by ITR after March 2004. This page is written by Johnny Lin and is last updated March 24, 2004.

Distribution Structure

Packages distributions have the following directory structure:

/package_directory
   /doc
       /imgs
       /style
   /src
   /lib
   /test
   README.txt
   setup.py

All names of files and directories are as given above, except package_directory which is the name of the package distribution directory given by the author. Generally, it is made of the package name followed by a hyphen and the version number. For instance, atmqty-0.3.0.1 contains version 0.3.0.1 of package atmqty.

Compiled source goes in /src, Python code in /lib, documentation (including pydoc HTML documentation) in /doc (imgs and style are for images and CSS files respectively), and test scripts in /test. Thus, install occurs by:

python setup.py install

via the distutils package.

HTML Documentation Templates

All HTML documentation (not created by pydoc) for the packages should be based upon the template.html and librootcsc.css HTML and CSS files below. This includes bug reports, examples, manuals, and other references.

template.html: The template HTML file. All the lines marked [@@@] are for you to fill in what you want. Remember to remove the brackets too. Last updated 24 Mar 2004.
librootcsc.css: The template CSS file. Remember that this file should be in directory style in the package distribution tree. Last updated 29 Mar 2004.
block_diagram.sxd: An OpenOffice Draw document showing the block layout I assume in designing the template HTML file, and what the CSS class names for those blocks are. Note that the class names have no tag delimiters (i.e. <> marks) while I show two structural tags (<body> and <address>) and how they are nested in relation to the class blocks. Last updated 24 Mar 2004.

A few notes about the templates:

CSS 1 does not support fine adjustment of tables (that's available in CSS 2 but CSS 2 isn't implemented universally). Thus, the module list table (which is defined in its own class modlist and delineated in a div) only controls coloring by CSS...the HTML file controls the cellpadding, etc. values.
I create a div class center to replace the <center> tag for both text and tables. You use it within <div class="center">...</div> because <center> is deprecated in HTML 4.01.
At the bottom of the HTML template are buttons to validate the HTML and source files to W3C standards, which will ensure compatibility to all browsers (or at least it's supposed to).

Climate Systems Center at the University of Chicago

Package Distribution Structure and HTML Documentation Template

General

Distribution Structure

HTML Documentation Templates