- removed conditional setuptool support from setup.py (now only requires

  distutils)

- fixed setup_egg.py which incorrect specified setuptools option 'zip_safe' as
  True (must be False to support data file lookups)

- added egg builds to release.sh

- epydoc now uses a config file and a custom CSS stylesheet

- added attribution for Python Cookbook recipe

2 files changed, 476 insertions, 0 deletions

diff --git a/docs/epydoc.cfg b/docs/epydoc.cfg
new file mode 100644
index 0000000..2e792d1
--- /dev/null
+++ b/docs/epydoc.cfg
@@ -0,0 +1,154 @@
+#   Equivalent command line :-

+#   epydoc --html --output ./docs/api/ --name netaddr --graph all

+#   --inheritance grouped --debug --verbose --no-private --no-sourcecode

+#   --css=./docs/epydoc.css netaddr

+

+[epydoc] # Epydoc section marker (required by ConfigParser)

+

+# The list of objects to document.  Objects can be named using

+# dotted names, module filenames, or package directory names.

+# Alases for this option include "objects" and "values".

+modules: netaddr

+

+# The type of output that should be generated.  Should be one

+# of: html, text, latex, dvi, ps, pdf.

+output: html

+

+# The path to the output directory.  May be relative or absolute.

+target: docs/api

+

+# An integer indicating how verbose epydoc should be.  The default

+# value is 0; negative values will supress warnings and errors;

+# positive values will give more verbose output.

+verbosity: 1

+

+# A boolean value indicating that Epydoc should show a tracaback

+# in case of unexpected error. By default don't show tracebacks

+debug: 1

+

+# If True, don't try to use colors or cursor control when doing

+# textual output. The default False assumes a rich text prompt

+simple-term: 0

+

+

+### Generation options

+

+# The default markup language for docstrings, for modules that do

+# not define __docformat__.  Defaults to epytext.

+docformat: epytext

+

+# Whether or not parsing should be used to examine objects.

+parse: yes

+

+# Whether or not introspection should be used to examine objects.

+introspect: yes

+

+# Don't examine in any way the modules whose dotted name match this

+# regular expression pattern.

+#exclude

+

+# Don't perform introspection on the modules whose dotted name match this

+# regular expression pattern.

+#exclude-introspect

+

+# Don't perform parsing on the modules whose dotted name match this

+# regular expression pattern.

+#exclude-parse

+

+# The format for showing inheritance objects.

+# It should be one of: 'grouped', 'listed', 'included'.

+inheritance: grouped

+

+# Whether or not to inclue private variables.  (Even if included,

+# private variables will be hidden by default.)

+private: yes

+

+# Whether or not to list each module's imports.

+imports: no

+

+# Whether or not to include syntax highlighted source code in

+# the output (HTML only).

+sourcecode: yes

+

+# Whether or not to includea a page with Epydoc log, containing

+# effective option at the time of generation and the reported logs.

+include-log: no

+

+

+### Output options

+

+# The documented project's name.

+#name: Example

+

+# The CSS stylesheet for HTML output.  Can be the name of a builtin

+# stylesheet, or the name of a file.

+#css: white

+css: docs/epydoc.css

+

+# The documented project's URL.

+url: http://netaddr.googlecode.com/

+

+# HTML code for the project link in the navigation bar.  If left

+# unspecified, the project link will be generated based on the

+# project's name and URL.

+#link: <a href="somewhere">My Cool Project</a>

+

+# The "top" page for the documentation.  Can be a URL, the name

+# of a module or class, or one of the special names "trees.html",

+# "indices.html", or "help.html"

+#top: os.path

+

+# An alternative help file.  The named file should contain the

+# body of an HTML file; navigation bars will be added to it.

+#help: my_helpfile.html

+

+# Whether or not to include a frames-based table of contents.

+frames: yes

+

+# Whether each class should be listed in its own section when

+# generating LaTeX or PDF output.

+separate-classes: no

+

+

+### API linking options

+

+# Define a new API document.  A new interpreted text role

+# will be created

+#external-api: epydoc

+

+# Use the records in this file to resolve objects in the API named NAME.

+#external-api-file: epydoc:api-objects.txt

+

+# Use this URL prefix to configure the string returned for external API.

+#external-api-root: epydoc:http://epydoc.sourceforge.net/api

+

+

+### Graph options

+

+# The list of graph types that should be automatically included

+# in the output.  Graphs are generated using the Graphviz "dot"

+# executable.  Graph types include: "classtree", "callgraph",

+# "umlclass".  Use "all" to include all graph types

+#graph: all

+

+# The path to the Graphviz "dot" executable, used to generate

+# graphs.

+#dotpath: /usr/local/bin/dot

+

+# The name of one or more pstat files (generated by the profile

+# or hotshot module).  These are used to generate call graphs.

+#pstat: profile.out

+

+# Specify the font used to generate Graphviz graphs.

+# (e.g., helvetica or times).

+#graph-font: Helvetica

+

+# Specify the font size used to generate Graphviz graphs.

+#graph-font-size: 10

+

+

+### Return value options

+

+# The condition upon which Epydoc should exit with a non-zero

+# exit status. Possible values are error, warning, docstring_warning

+fail-on: error

diff --git a/docs/epydoc.css b/docs/epydoc.css
new file mode 100644
index 0000000..d70ef81
--- /dev/null
+++ b/docs/epydoc.css
@@ -0,0 +1,322 @@
+/* Epydoc CSS Stylesheet
+ *
+ * This stylesheet can be used to customize the appearance of epydoc's
+ * HTML output.
+ *
+ */
+
+/* Default Colors & Styles
+ *   - Set the default foreground & background color with 'body'; and 
+ *     link colors with 'a:link' and 'a:visited'.
+ *   - Use bold for decision list terms.
+ *   - The heading styles defined here are used for headings *within*
+ *     docstring descriptions.  All headings used by epydoc itself use
+ *     either class='epydoc' or class='toc' (CSS styles for both
+ *     defined below).
+ */
+body                        { background: #ffffff; color: #000000;
+                              font-family: sans-serif; font-size: 10pt }
+p                           { margin-top: 0.5em; margin-bottom: 0.5em; }
+
+a 							{ text-decoration: none; color: #eb1400; }
+a:hover 					{ text-decoration: underline; color: #ad200e; }
+a:link                      { color: #eb1400; }
+a:visited                   { color: #eb1400; }
+dt                          { font-weight: bold; }
+h1                          { font-size: +140%; font-weight: bold; }
+h2                          { font-size: +125%; font-weight: bold; }
+h3                          { font-size: +110%;  font-weight: normal; }
+code                        { font-size: 100%; }
+/* N.B.: class, not pseudoclass */
+a.link                      { font-family: monospace; }
+ 
+/* Page Header & Footer
+ *   - The standard page header consists of a navigation bar (with
+ *     pointers to standard pages such as 'home' and 'trees'); a
+ *     breadcrumbs list, which can be used to navigate to containing
+ *     classes or modules; options links, to show/hide private
+ *     variables and to show/hide frames; and a page title (using
+ *     <h1>).  The page title may be followed by a link to the
+ *     corresponding source code (using 'span.codelink').
+ *   - The footer consists of a navigation bar, a timestamp, and a
+ *     pointer to epydoc's homepage.
+ */ 
+h1.epydoc                   { margin: 0; font-size: +140%; font-weight: bold; }
+h2.epydoc                   { font-size: +130%; font-weight: bold; }
+h3.epydoc                   { font-size: +115%; font-weight: bold;
+                              margin-top: 0.2em; }
+td h3.epydoc                { font-size: +115%; font-weight: bold;
+                              margin-bottom: 0; }
+table.navbar                { background: #ef2200; color: #626262;
+                              border: solid 2px #000000; border-collapse: collapse;}
+table.navbar table          { color: #626262; padding: 0.5em }
+th.navbar-select            { background: #fff29c; color: #ef2200; border: solid 2px #000000;} 
+table.navbar a              { text-decoration: none; }  
+table.navbar a:link         { color: #ffffff; }
+table.navbar a:visited      { color: #204080; }
+span.breadcrumbs            { font-size: 85%; font-weight: bold; }
+span.options                { font-size: 70%; }
+span.codelink               { font-size: 85%; }
+td.footer                   { font-size: 85%; }
+
+/* Table Headers
+ *   - Each summary table and details section begins with a 'header'
+ *     row.  This row contains a section title (marked by
+ *     'span.table-header') as well as a show/hide private link
+ *     (marked by 'span.options', defined above).
+ *   - Summary tables that contain user-defined groups mark those
+ *     groups using 'group header' rows.
+ */
+td.table-header             { background: #ef2200; color: #ffffff;
+                              border: solid 2px #000000; }
+td.table-header table       { color: #ffffff; }
+td.table-header table a:link      { color: #ffffff; }
+td.table-header table a:hover     { color: #ffffff;text-decoration: underline; }
+td.table-header table a:visited   { color: #ffffff; }
+span.table-header           { font-size: 120%; font-weight: bold; color: #ffffff;}
+th.group-header             { background: #fff197; color: #ef2200;
+                              text-align: left; font-style: italic; 
+                              font-size: 115%; 
+                              border: dotted 1px #626262; }
+
+/* Summary Tables (functions, variables, etc)
+ *   - Each object is described by a single row of the table with
+ *     two cells.  The left cell gives the object's type, and is
+ *     marked with 'code.summary-type'.  The right cell gives the
+ *     object's name and a summary description.
+ *   - CSS styles for the table's header and group headers are
+ *     defined above, under 'Table Headers'
+ */
+table.summary               { border-collapse: collapse;
+                              background: #fffcd8; color: #626262;
+                              border: dotted 1px #626262;
+                              margin-bottom: 0.5em; }
+td.summary                  { border: dotted 1px #626262; }
+code.summary-type           { font-size: 85%; }
+table.summary a:link        { color: #626262; }
+table.summary a:visited     { color: #626262; }
+
+
+/* Details Tables (functions, variables, etc)
+ *   - Each object is described in its own div.
+ *   - A single-row summary table w/ table-header is used as
+ *     a header for each details section (CSS style for table-header
+ *     is defined above, under 'Table Headers').
+ */
+table.details               { border-collapse: collapse;
+                              background: #fffcd8; color: #626262;
+                              border: dotted 1px #626262;
+                              margin: .2em 0 0 0; }
+table.details table         { color: #626262; }
+table.details a:link        { color: #626262; }
+table.details a:visited     { color: #626262; }
+
+/* Fields */
+dl.fields                   { margin-left: 2em; margin-top: 1em;
+                              margin-bottom: 1em; }
+dl.fields dd ul             { margin-left: 0em; padding-left: 0em; }
+dl.fields dd ul li ul       { margin-left: 2em; padding-left: 0em; }
+div.fields                  { margin-left: 2em; }
+div.fields p                { margin-bottom: 0.5em; }
+
+/* Index tables (identifier index, term index, etc)
+ *   - link-index is used for indices containing lists of links
+ *     (namely, the identifier index & term index).
+ *   - index-where is used in link indices for the text indicating
+ *     the container/source for each link.
+ *   - metadata-index is used for indices containing metadata
+ *     extracted from fields (namely, the bug index & todo index).
+ */
+table.link-index            { border-collapse: collapse;
+                              background: #fffcd8; color: #626262;
+                              border: dotted 1px #626262; }
+td.link-index               { border-width: 0px; }
+table.link-index a:link     { color: #626262; }
+table.link-index a:visited  { color: #626262; }
+span.index-where            { font-size: 70%; }
+table.metadata-index        { border-collapse: collapse;
+                              background: #fffcd8; color: #626262;
+                              border: dotted 1px #626262; 
+                              margin: .2em 0 0 0; }
+td.metadata-index           { border-width: dotted 1px #626262; }
+table.metadata-index a:link { color: #0000ff; }
+table.metadata-index a:visited  { color: #204080; }
+
+/* Function signatures
+ *   - sig* is used for the signature in the details section.
+ *   - .summary-sig* is used for the signature in the summary 
+ *     table, and when listing property accessor functions.
+ * */
+.sig                   { color: #4292D3; font-family: monospace; font-weight: bold;  font-size: 110%; }
+.sig-name                   { color: #4292D3;}
+.sig-arg                    { color: #4292D3;}
+.sig-default                { color: #4292D3;}
+.summary-sig                { font-family: monospace; }
+.summary-sig-name           { color: #006080; font-weight: bold; }
+table.summary a.summary-sig-name:link
+                            { color: #006080; font-weight: bold; }
+table.summary a.summary-sig-name:visited
+                            { color: #006080; font-weight: bold; }
+.summary-sig-arg            { color: #006040; }
+.summary-sig-default        { color: #501800; }
+
+/* Subclass list
+ */
+ul.subclass-list { display: inline; }
+ul.subclass-list li { display: inline; }
+
+/* To render variables, classes etc. like functions */
+table.summary .summary-name { color: #006080; font-weight: bold;
+                              font-family: monospace; }
+table.summary
+     a.summary-name:link    { color: #006080; font-weight: bold;
+                              font-family: monospace; }
+table.summary
+    a.summary-name:visited  { color: #006080; font-weight: bold;
+                              font-family: monospace; }
+
+/* Variable values
+ *   - In the 'variable details' sections, each varaible's value is
+ *     listed in a 'pre.variable' box.  The width of this box is
+ *     restricted to 80 chars; if the value's repr is longer than
+ *     this it will be wrapped, using a backslash marked with
+ *     class 'variable-linewrap'.  If the value's repr is longer
+ *     than 3 lines, the rest will be ellided; and an ellipsis
+ *     marker ('...' marked with 'variable-ellipsis') will be used.
+ *   - If the value is a string, its quote marks will be marked
+ *     with 'variable-quote'.
+ *   - If the variable is a regexp, it is syntax-highlighted using
+ *     the re* CSS classes.
+ */
+pre.variable                { padding: .5em; margin: 0;
+                              background: #ffffff; color: #626262;
+                              border: dotted 1px #626262; }
+.variable-linewrap          { color: #604000; font-weight: bold; }
+.variable-ellipsis          { color: #604000; font-weight: bold; }
+.variable-quote             { color: #604000; font-weight: bold; }
+.variable-group             { color: #008000; font-weight: bold; }
+.variable-op                { color: #604000; font-weight: bold; }
+.variable-string            { color: #006030; }
+.variable-unknown           { color: #a00000; font-weight: bold; }
+.re                         { color: #626262; }
+.re-char                    { color: #006030; }
+.re-op                      { color: #600000; }
+.re-group                   { color: #003060; }
+.re-ref                     { color: #404040; }
+
+/* Base tree
+ *   - Used by class pages to display the base class hierarchy.
+ */
+pre.base-tree               { font-size: 80%; margin: 0; }
+
+/* Frames-based table of contents headers
+ *   - Consists of two frames: one for selecting modules; and
+ *     the other listing the contents of the selected module.
+ *   - h1.toc is used for each frame's heading
+ *   - h2.toc is used for subheadings within each frame.
+ */
+h1.toc                      { text-align: center; font-size: 105%;
+                              margin: 0; font-weight: bold;
+                              padding: 0; }
+h2.toc                      { font-size: 100%; font-weight: bold; 
+                              margin: 0.5em 0 0 -0.3em; }
+
+/* Syntax Highlighting for Source Code
+ *   - doctest examples are displayed in a 'pre.py-doctest' block.
+ *     If the example is in a details table entry, then it will use
+ *     the colors specified by the 'table pre.py-doctest' line.
+ *   - Source code listings are displayed in a 'pre.py-src' block.
+ *     Each line is marked with 'span.py-line' (used to draw a line
+ *     down the left margin, separating the code from the line
+ *     numbers).  Line numbers are displayed with 'span.py-lineno'.
+ *     The expand/collapse block toggle button is displayed with
+ *     'a.py-toggle' (Note: the CSS style for 'a.py-toggle' should not
+ *     modify the font size of the text.)
+ *   - If a source code page is opened with an anchor, then the
+ *     corresponding code block will be highlighted.  The code
+ *     block's header is highlighted with 'py-highlight-hdr'; and
+ *     the code block's body is highlighted with 'py-highlight'.
+ *   - The remaining py-* classes are used to perform syntax
+ *     highlighting (py-string for string literals, py-name for names,
+ *     etc.)
+ */
+pre.py-doctest              { padding: .5em; margin: 1em;
+                              background: #fffcd8; color: #626262;
+                              border: 1px solid #708890; }
+table pre.py-doctest        { background: #dce4ec;
+                              color: #626262; }
+pre.py-src                  { border: 1px dotted #000000; 
+                              background: #ffffff; color: #000000; }
+.py-line                    { border-left: 1px dotted #626262; 
+                              margin-left: .2em; padding-left: .4em; }
+.py-lineno                  { font-size: 90%;
+                              padding-left: .5em; color: #808080 }
+a.py-toggle                 { text-decoration: none; }
+div.py-highlight-hdr        { border-top: 1px dotted #626262;
+                              border-bottom: 1px dotted #626262;
+                              background: #fff197; }
+div.py-highlight            { border-bottom: 1px dotted #626262;
+                              background: #fffcd8; }
+.py-prompt                  { color: #005050; font-weight: bold;}
+.py-more                    { color: #005050; font-weight: bold;}
+.py-string                  { color: #808080; }
+.py-comment                 { color: #008000; background: #e1ffe1; }
+.py-keyword                 { color: #0000ff; font-weight: bold; }
+.py-output                  { color: #404040; }
+.py-name                    { color: #000050; }
+.py-name:link               { color: #000050 !important; }
+.py-name:visited            { color: #000050 !important; }
+.py-number                  { color: #005000; }
+.py-defname                 { color: #000060; font-weight: bold; }
+.py-def-name                { color: #000060; font-weight: bold; }
+.py-base-class              { color: #000060; }
+.py-param                   { color: #000060; }
+.py-docstring               { color: #008000; background: #e1ffe1 }
+.py-decorator               { color: #804020; }
+/* Use this if you don't want links to names underlined: */
+/*a.py-name                   { text-decoration: none; }*/
+
+/* Graphs & Diagrams
+ *   - These CSS styles are used for graphs & diagrams generated using
+ *     Graphviz dot.  'img.graph-without-title' is used for bare
+ *     diagrams (to remove the border created by making the image
+ *     clickable).
+ */
+img.graph-without-title     { border: none; }
+img.graph-with-title        { border: 1px solid #626262; }
+span.graph-title            { font-weight: bold; }
+span.graph-caption          { }
+
+/* General-purpose classes
+ *   - 'p.indent-wrapped-lines' defines a paragraph whose first line
+ *     is not indented, but whose subsequent lines are.
+ *   - The 'nomargin-top' class is used to remove the top margin (e.g.
+ *     from lists).  The 'nomargin' class is used to remove both the
+ *     top and bottom margin (but not the left or right margin --
+ *     for lists, that would cause the bullets to disappear.)
+ */
+p.indent-wrapped-lines      { padding: 0 0 0 7em; text-indent: -7em; 
+                              margin: 0; }
+.nomargin-top               { margin-top: 0; }
+.nomargin                   { margin-top: 0; margin-bottom: 0; }
+
+/* HTML Log */
+div.log-block               { padding: 0; margin: .5em 0 .5em 0;
+                              background: #fffcd8; color: #626262;
+                              border: 1px solid #626262; }
+div.log-error               { padding: .1em .3em .1em .3em; margin: 4px;
+                              background: #ffb0b0; color: #626262;
+                              border: 1px solid #626262; }
+div.log-warning             { padding: .1em .3em .1em .3em; margin: 4px;
+                              background: #ffffb0; color: #626262;
+                              border: 1px solid #626262; }
+div.log-info               { padding: .1em .3em .1em .3em; margin: 4px;
+                              background: #b0ffb0; color: #626262;
+                              border: 1px solid #626262; }
+h2.log-hdr                  { background: #ef2200; color: #626262;
+                              margin: 0; padding: 0em 0.5em 0em 0.5em;
+                              border-bottom: 1px solid #626262; font-size: 110%; }
+p.log                       { font-weight: bold; margin: .5em 0 .5em 0; }
+tr.opt-changed              { color: #626262; font-weight: bold; }
+tr.opt-default              { color: #606060; }
+pre.log                     { margin: 0; padding: 0; padding-left: 1em; }