improve doc for better epydoc generation (again).

19 files changed, 263 insertions, 242 deletions

diff --git a/__init__.py b/__init__.py
index 5367194..64d7cce 100644
--- a/__init__.py
+++ b/__init__.py
@@ -1,6 +1,4 @@
-"""Logilab common library.
-
-A set of common functionnalities shared by Logilab's projects.
+"""Logilab common library (aka Logilab's extension to the standard library).
 
 :type STD_BLACKLIST: tuple
 :var STD_BLACKLIST: directories ignored by default by the functions in
@@ -9,10 +7,17 @@ A set of common functionnalities shared by Logilab's projects.
 :type IGNORED_EXTENSIONS: tuple
 :var IGNORED_EXTENSIONS: file extensions that may usually be ignored
 
-:organization: Logilab
-:copyright: 2000-2008 LOGILAB S.A. (Paris, FRANCE), all rights reserved.
-:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
-:license: General Public License version 2 - http://www.gnu.org/licenses
+:copyright:
+  2000-2008 `LOGILAB S.A. <http://www.logilab.fr>`_ (Paris, FRANCE),
+  all rights reserved.
+
+:contact:
+  http://www.logilab.org/project/logilab-common --
+  mailto:python-projects@logilab.org
+
+:license:
+  `General Public License version 2
+  <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>`_
 """
 __docformat__ = "restructuredtext en"
 from logilab.common.__pkginfo__ import version as __version__
@@ -22,7 +27,6 @@ STD_BLACKLIST = ('CVS', '.svn', '.hg', 'debian', 'dist', 'build')
 IGNORED_EXTENSIONS = ('.pyc', '.pyo', '.elc', '~')
 
 
-
 from logilab.common.deprecation import moved
 
 get_cycles = moved('logilab.common.graph', 'get_cycles')
@@ -35,7 +39,7 @@ deprecated_function = moved('logilab.common.deprecation', 'deprecated_function')
 class_renamed = moved('logilab.common.deprecation', 'class_renamed')
 
 def intersection(list1, list2):
-    """return the intersection of list1 and list2"""
+    """Return the intersection of list1 and list2."""
     warn('this function is deprecated, use a set instead', DeprecationWarning,
          stacklevel=2)
     intersect_dict, result = {}, []
@@ -47,7 +51,7 @@ def intersection(list1, list2):
     return result
 
 def difference(list1, list2):
-    """return elements of list1 not in list2"""
+    """Return elements of list1 not in list2."""
     warn('this function is deprecated, use a set instead', DeprecationWarning,
          stacklevel=2)
     tmp, result = {}, []
@@ -59,7 +63,7 @@ def difference(list1, list2):
     return result
 
 def union(list1, list2):
-    """return list1 union list2"""
+    """Return list1 union list2."""
     warn('this function is deprecated, use a set instead', DeprecationWarning,
          stacklevel=2)
     tmp = {}
@@ -71,7 +75,7 @@ def union(list1, list2):
 
 
 class attrdict(dict):
-    """a dictionary whose keys are also accessible as attributes"""
+    """A dictionary for which keys are also accessible as attributes."""
     def __getattr__(self, attr):
         try:
             return self[attr]
@@ -108,10 +112,15 @@ class nullobject(object):
 #               yield subitem
 
 def flatten(iterable, tr_func=None, results=None):
-    """flatten a list of list with any level
+    """Flatten a list of list with any level.
 
-    if tr_func is not None, it should be a one argument function that'll be called
-    on each final element
+    If tr_func is not None, it should be a one argument function that'll be called
+    on each final element.
+
+    :rtype: list
+
+    >>> flatten([1, [2, 3]])
+    [1, 2, 3]
     """
     if results is None:
         results = []
@@ -129,12 +138,15 @@ def flatten(iterable, tr_func=None, results=None):
 
 def make_domains(lists):
     """
-    given a list of lists, return a list of domain for each list to produce all
-    combinaisons of possibles values
+    Given a list of lists, return a list of domain for each list to produce all
+    combinations of possibles values.
+
+    :rtype: list
+    
+    Example:
 
-    ex: (['a', 'b'], ['c','d', 'e'])
-       -> (['a', 'b', 'a', 'b', 'a', 'b'],
-           ['c', 'c', 'd', 'd', 'e', 'e'])
+    >>> make_domains(['a', 'b'], ['c','d', 'e'])
+    [['a', 'b', 'a', 'b', 'a', 'b'], ['c', 'c', 'd', 'd', 'e', 'e']]
     """
     domains = []
     for iterable in lists:
diff --git a/adbh.py b/adbh.py
index c772e8b..f496b1a 100644
--- a/adbh.py
+++ b/adbh.py
@@ -2,9 +2,17 @@
 
 Helpers are provided for postgresql, mysql and sqlite.
 
-:copyright: 2000-2008 LOGILAB S.A. (Paris, FRANCE), all rights reserved.
-:contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
-:license: General Public License version 2 - http://www.gnu.org/licenses
+:copyright:
+  2000-2008 `LOGILAB S.A. <http://www.logilab.fr>`_ (Paris, FRANCE),
+  all rights reserved.
+
+:contact:
+  http://www.logilab.org/project/logilab-common --
+  mailto:python-projects@logilab.org
+
+:license:
+  `General Public License version 2
+  <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>`_
 """
 __docformat__ = "restructuredtext en"
 
diff --git a/changelog.py b/changelog.py
index 91b30da..d4274d7 100644
--- a/changelog.py
+++ b/changelog.py
@@ -3,22 +3,21 @@
 The upstream change log files format handled is simpler than the one
 often used such as those generated by the default Emacs changelog mode.
 
-Sample ChangeLog format:
-------------------------------------------------------------
-Change log for project Yoo
-==========================
+Sample ChangeLog format::
 
- --
-    * add a new functionnality
+  Change log for project Yoo
+  ==========================
+  
+   --
+      * add a new functionnality
 
-2002-02-01 -- 0.1.1
-    * fix bug #435454
-    * fix bug #434356
+  2002-02-01 -- 0.1.1
+      * fix bug #435454
+      * fix bug #434356
     
-2002-01-01 -- 0.1
-    * initial release
+  2002-01-01 -- 0.1
+      * initial release
     
-------------------------------------------------------------
 
 There is 3 entries in this change log, one for each released version and one
 for the next version (i.e. the current entry).
diff --git a/cli.py b/cli.py
index cc7c373..8c37f77 100644
--- a/cli.py
+++ b/cli.py
@@ -1,9 +1,9 @@
 """Command line interface helper classes.
  
 It provides some default commands, a help system, a default readline
-configuration with completion and persistent history
+configuration with completion and persistent history.
 
-Exemple usage:
+Example::
 
     class BookShell(CLIHelper):
 
@@ -36,7 +36,7 @@ if not hasattr(__builtin__, '_'):
     
 
 def init_readline(complete_method, histfile=None):
-    """init the readline library if available"""
+    """Init the readline library if available."""
     try:
         import readline
         readline.parse_and_bind("tab: complete")
@@ -55,13 +55,13 @@ def init_readline(complete_method, histfile=None):
 
 
 class Completer :
-    """readline completer"""
+    """Readline completer."""
     
     def __init__(self, commands):
         self.list = commands
         
     def complete(self, text, state):
-        """hook called by readline when <tab> is pressed"""
+        """Hook called by readline when <tab> is pressed."""
         n = len(text)
         matches = []
         for cmd in self.list :
@@ -74,8 +74,8 @@ class Completer :
 
 
 class CLIHelper:
-    """ an abstract command line interface client which recognize commands
-    and provide an help system
+    """An abstract command line interface client which recognize commands
+    and provide an help system.
     """
     
     CMD_MAP = {'help' : _("Others"),
@@ -118,9 +118,8 @@ class CLIHelper:
                     traceback.print_exc()
 
     def handle_line(self, stripped_line):
-        """method to overload in the concrete class
-        
-        should handle lines wich are not command
+        """Method to overload in the concrete class (should handle
+        lines wich are not commands).
         """
         raise NotImplementedError()
 
diff --git a/compat.py b/compat.py
index 5252ded..6010340 100644
--- a/compat.py
+++ b/compat.py
@@ -1,3 +1,4 @@
+# pylint: disable-msg=E0601,W0622,W0611
 """Wrappers around some builtins introduced in python 2.3, 2.4 and
 2.5, making them available in for earlier versions of python.
 
@@ -5,11 +6,8 @@
 :contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
 :license: General Public License version 2 - http://www.gnu.org/licenses
 """
-__docformat__ = "restructuredtext en"
-
-# pylint: disable-msg=E0601,W0622,W0611
-
 from __future__ import generators
+__docformat__ = "restructuredtext en"
 
 from warnings import warn
 
diff --git a/configuration.py b/configuration.py
index 5389952..9fcac36 100644
--- a/configuration.py
+++ b/configuration.py
@@ -1,64 +1,94 @@
-"""Some classes used to handle advanced configuration in simple to
-complex applications.
+"""Classes to handle advanced configuration in simple to complex applications.
 
-It's able to load the configuration from a file and or command line
-options, to generate a sample configuration file or to display program's
-usage. It basically fill the gap between optik/optparse and ConfigParser,
-with some additional data types (available as standalone optik extension
-in the `optik_ext` module)
+Allows to load the configuration from a file or from command line
+options, to generate a sample configuration file or to display
+program's usage. Fills the gap between optik/optparse and ConfigParser
+by adding data types (which are also available as a standalone optik
+extension in the `optik_ext` module).
 
 
 Quick start: simplest usage
 ---------------------------
 
-import sys
-from logilab.common.configuration import Configuration
-
-options = [('dothis', {'type':'yn', 'default': True, 'metavar': '<y or n>'}),
-           ('value', {'type': 'string', 'metavar': '<string>'}),
-           ('multiple', {'type': 'csv', 'default': ('yop',),
-                         'metavar': '<comma separated values>',
-                         'help': 'you can also document the option'}),
-           ('number', {'type': 'int', 'default':2, 'metavar':'<int>'}),
-           ]
-config = Configuration(options=options, name='My config')
-print config['dothis']
-print config['value']
-print config['multiple']
-print config['number']
-
-print config.help()
-
-f = open('myconfig.ini', 'w')
-f.write('''[MY CONFIG]
-number = 3
-dothis = no
-multiple = 1,2,3
-''')
-f.close()
-config.load_file_configuration('myconfig.ini')
-print config['dothis']
-print config['value']
-print config['multiple']
-print config['number']
-
-sys.argv = ['mon prog', '--value', 'bacon', '--multiple', '4,5,6',
-            'nonoptionargument']
-print config.load_command_line_configuration()
-print config['value']
-
-config.generate_config()
+.. python ::
+
+  >>> import sys
+  >>> from logilab.common.configuration import Configuration
+  >>> options = [('dothis', {'type':'yn', 'default': True, 'metavar': '<y or n>'}),
+  ...            ('value', {'type': 'string', 'metavar': '<string>'}),
+  ...            ('multiple', {'type': 'csv', 'default': ('yop',),
+  ...                          'metavar': '<comma separated values>',
+  ...                          'help': 'you can also document the option'}),
+  ...            ('number', {'type': 'int', 'default':2, 'metavar':'<int>'}),
+  ...           ]
+  >>> config = Configuration(options=options, name='My config')
+  >>> print config['dothis']
+  True
+  >>> print config['value']
+  None
+  >>> print config['multiple']
+  ('yop',)
+  >>> print config['number']
+  2
+  >>> print config.help()
+  Usage:  [options]
+  
+  Options:
+    -h, --help            show this help message and exit
+    --dothis=<y or n>     
+    --value=<string>      
+    --multiple=<comma separated values>
+                          you can also document the option [current: none]
+    --number=<int>        
+  
+  >>> f = open('myconfig.ini', 'w')
+  >>> f.write('''[MY CONFIG]
+  ... number = 3
+  ... dothis = no
+  ... multiple = 1,2,3
+  ... ''')
+  >>> f.close()
+  >>> config.load_file_configuration('myconfig.ini')
+  >>> print config['dothis']
+  False
+  >>> print config['value']
+  None
+  >>> print config['multiple']
+  ['1', '2', '3']
+  >>> print config['number']
+  3
+  >>> sys.argv = ['mon prog', '--value', 'bacon', '--multiple', '4,5,6',
+  ...             'nonoptionargument']
+  >>> print config.load_command_line_configuration()
+  ['nonoptionargument']
+  >>> print config['value']
+  bacon
+  >>> config.generate_config()
+  # class for simple configurations which don't need the
+  # manager / providers model and prefer delegation to inheritance
+  # 
+  # configuration values are accessible through a dict like interface
+  # 
+  [MY CONFIG]
+  
+  dothis=no
+  
+  value=bacon
+  
+  # you can also document the option
+  multiple=4,5,6
+  
+  number=3
+  >>>
 
 
 :copyright: 2003-2008 LOGILAB S.A. (Paris, FRANCE), all rights reserved.
 :contact: http://www.logilab.fr/ -- mailto:contact@logilab.fr
 :license: General Public License version 2 - http://www.gnu.org/licenses
 """
-__docformat__ = "restructuredtext en"
-
 from __future__ import generators 
-
 __docformat__ = "restructuredtext en"
+
 __all__ = ('OptionsManagerMixIn', 'OptionsProviderMixIn',
            'ConfigurationMixIn', 'Configuration',
            'OptionsManager2ConfigurationAdapter')
diff --git a/deprecation.py b/deprecation.py
index c7ffe59..b103092 100644
--- a/deprecation.py
+++ b/deprecation.py
@@ -61,9 +61,10 @@ def class_moved(new_class, old_name=None, message=None):
 
 
 def deprecated_function(new_func, message=None):
-    """creates a function which fires a DeprecationWarning when used
+    """Creates a function which fires a DeprecationWarning when used.
 
-    For example, if <bar> is deprecated in favour of <foo> :
+    For example, if <bar> is deprecated in favour of <foo>:
+    
     >>> bar = deprecated_function(foo, 'bar is deprecated')
     >>> bar()
     sample.py:57: DeprecationWarning: bar is deprecated
diff --git a/graph.py b/graph.py
index 3333652..b2f9c04 100644
--- a/graph.py
+++ b/graph.py
@@ -59,8 +59,10 @@ class DotBackend:
     def generate(self, outputfile=None, dotfile=None):
         """Generates a graph file.
         
-        :param target: output format ('png', 'ps', etc.). If None,
-                       the raw dot source will be returned
+        :param outputfile: filename and path [defaults to graphname.png]
+        :param dotfile: filename and path [defaults to graphname.dot]
+        
+        :rtype: str
         :return: a path to the generated file
         """
         if outputfile is not None:
diff --git a/modutils.py b/modutils.py
index 63b33a9..a60ae7d 100644
--- a/modutils.py
+++ b/modutils.py
@@ -65,7 +65,7 @@ class LazyObject(object):
 
 
 def load_module_from_name(dotted_name, path=None, use_sys=1):
-    """load a Python module from it's name
+    """Load a Python module from it's name.
 
     :type dotted_name: str
     :param dotted_name: python name of a module or package
@@ -90,7 +90,7 @@ def load_module_from_name(dotted_name, path=None, use_sys=1):
 
 
 def load_module_from_modpath(parts, path=None, use_sys=1):
-    """load a python module from it's splitted name
+    """Load a python module from it's splitted name.
 
     :type parts: list(str) or tuple(str)
     :param parts:
@@ -105,9 +105,6 @@ def load_module_from_modpath(parts, path=None, use_sys=1):
     :param use_sys:
       boolean indicating whether the sys.modules dictionary should be used or not
 
-    :param _prefix: used internally, should not be specified
-
-
     :raise ImportError: if the module or package is not found
     
     :rtype: module
@@ -141,10 +138,10 @@ def load_module_from_modpath(parts, path=None, use_sys=1):
 
 
 def load_module_from_file(filepath, path=None, use_sys=1):
-    """load a Python module from it's path
+    """Load a Python module from it's path.
 
     :type filepath: str
-    :param dotted_name: path to the python module or package
+    :param filepath: path to the python module or package
 
     :type path: list or None
     :param path:
diff --git a/monserver.py b/monserver.py
index dc3f9d2..26fe959 100644
--- a/monserver.py
+++ b/monserver.py
@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""This module implements a TCP server in a separate thread that
+"""A TCP server implemented in a separate thread that
 allows *one* client to connect and provides a command line interpreter
 allowing the remote client to explore the process on the fly.
 
diff --git a/table.py b/table.py
index bc6c853..7121bcb 100644
--- a/table.py
+++ b/table.py
@@ -850,7 +850,7 @@ class DocbookRenderer(TableCellRenderer):
     def _render_cell_content(self, cell_content, table_style, col_index):
         """Makes the appropriate rendering for this cell content.
         Rendering properties will be searched using the
-        *table_style.get_xxx_by_index(col_index)' methods.
+        table_style.get_xxx_by_index(col_index)' methods.
         """
         try:
             align_on = self.properties['alignment']
diff --git a/testlib.py b/testlib.py
index d09b38f..6d33ba5 100644
--- a/testlib.py
+++ b/testlib.py
@@ -199,11 +199,10 @@ main = obsolete("testlib.main() is obsolete, use the pytest tool instead")(main)
 
 
 def run_tests(tests, quiet, verbose, runner=None, capture=0):
-    """ execute a list of tests
-    return a 3-uple with :
-       _ the list of passed tests
-       _ the list of failed tests
-       _ the list of skipped tests
+    """Execute a list of tests.
+
+    :rtype: tuple
+    :return: tuple (list of passed tests, list of failed tests, list of skipped tests)
     """
     good = []
     bad = []
@@ -535,10 +534,10 @@ class SkipAwareTextTestRunner(unittest.TextTestRunner):
 
 
 class keywords(dict):
-    """keyword args (**kwargs) support for generative tests"""
+    """Keyword args (**kwargs) support for generative tests."""
 
 class starargs(tuple):
-    """variable arguments (*args) for generative tests"""
+    """Variable arguments (*args) for generative tests."""
     def __new__(cls, *args):
         return tuple.__new__(cls, args)
 
@@ -546,9 +545,10 @@ class starargs(tuple):
 
 class NonStrictTestLoader(unittest.TestLoader):
     """
-    overrides default testloader to be able to omit classname when
-    specifying tests to run on command line. For example, if the file
-    test_foo.py contains ::
+    Overrides default testloader to be able to omit classname when
+    specifying tests to run on command line.
+
+    For example, if the file test_foo.py contains ::
     
         class FooTC(TestCase):
             def test_foo1(self): # ...
@@ -558,11 +558,11 @@ class NonStrictTestLoader(unittest.TestLoader):
         class BarTC(TestCase):
             def test_bar2(self): # ...
 
-    python test_foo.py will run the 3 tests in FooTC
-    python test_foo.py FooTC will run the 3 tests in FooTC
-    python test_foo.py test_foo will run test_foo1 and test_foo2
-    python test_foo.py test_foo1 will run test_foo1
-    python test_foo.py test_bar will run FooTC.test_bar1 and BarTC.test_bar2
+    'python test_foo.py' will run the 3 tests in FooTC
+    'python test_foo.py FooTC' will run the 3 tests in FooTC
+    'python test_foo.py test_foo' will run test_foo1 and test_foo2
+    'python test_foo.py test_foo1' will run test_foo1
+    'python test_foo.py test_bar' will run FooTC.test_bar1 and BarTC.test_bar2
     """
 
     def __init__(self):
@@ -1618,9 +1618,9 @@ def mock_object(**params):
 
 
 def create_files(paths, chroot):
-    """creates directories and files found in <path>
+    """Creates directories and files found in <path>.
 
-    :param path: list of relative paths to files or directories
+    :param paths: list of relative paths to files or directories
     :param chroot: the root directory in which paths will be created
 
     >>> from os.path import isdir, isfile
diff --git a/textutils.py b/textutils.py
index 2dfe319..fec946f 100644
--- a/textutils.py
+++ b/textutils.py
@@ -255,8 +255,8 @@ TIME_UNITS = {
 
 def apply_units( string, units, inter=None, final=float, blank_reg=_BLANK_RE,
     value_reg=_VALUE_RE):
-    """parse the string applying the units define in units
-    eg: "1.5m",{'m',60} -> 80
+    """Parse the string applying the units defined in units
+    (eg: "1.5m",{'m',60} -> 80).
         
     :type string: str or unicode
     :param string: the string to parse
@@ -266,20 +266,12 @@ def apply_units( string, units, inter=None, final=float, blank_reg=_BLANK_RE,
 
     :type inter: type
     :param inter: used to parse every intermediate value (need __sum__)
-    :default inter: final value
-
-    :type inter: type
-    :param inter: used to build the final object after summing them all
-    :default inter: float
     
     :type blank_reg: regexp
     :param blank_reg: should match eveyr blank char to ignore.
-    :default blank_reg: (\s|,)+ # match blank space and coma
     
     :type value_reg: regexp with "value" and optional "unit" group
     :param value_reg: match a value and it's unit into the 
-    :default value_reg: (-?(((0x?)?[0-9]+)|([0-9]+\\.[0-9]*)))([a-zA-Z]+)?
-        match any number 
     """
     if inter is None:
         inter = final
diff --git a/twisted_distutils.py b/twisted_distutils.py
index 72467e2..a705854 100644
--- a/twisted_distutils.py
+++ b/twisted_distutils.py
@@ -3,27 +3,27 @@
 This module enables the installation of plugins.tml files using standard
 distutils syntax. It adds the following commands to the standard
 setup.py commands:
- * build_twisted_plugins: build (i.e. copy) plugins
- * install_twisted_plugins: install plugins
+ - build_twisted_plugins: build (i.e. copy) plugins
+ - install_twisted_plugins: install plugins
 
 Additionally, the following commands have been modified to deal with
 plugins files:
- * sdist
- * build
- * install
+ - sdist
+ - build
+ - install
 
 To use these extenstion, you should import the setup fonction from this
 module, and use it normally. To list the plugins.tml files, use the
-twisted_plugins keyword argument to the setup function:
+twisted_plugins keyword argument to the setup function::
 
-from twisted_distutils import setup # you can also import Extension if needed
+  from twisted_distutils import setup # you can also import Extension if needed
 
-if __name__ == '__main__':
-    setup(name='my_twisted_app',
-          version='1.0',
-          author='me',
-          packages=['my_package'],
-          twisted_plugins = ['my_package/plugins.tml'])
+  if __name__ == '__main__':
+      setup(name='my_twisted_app',
+            version='1.0',
+            author='me',
+            packages=['my_package'],
+            twisted_plugins = ['my_package/plugins.tml'])
 
 Note that you can use this to install files that are not twisted plugins in any
 package directory of your application.
diff --git a/ureports/__init__.py b/ureports/__init__.py
index bb19ad5..210ec60 100644
--- a/ureports/__init__.py
+++ b/ureports/__init__.py
@@ -1,25 +1,22 @@
-# Copyright (c) 2004-2005 LOGILAB S.A. (Paris, FRANCE).
-# http://www.logilab.fr/ -- mailto:contact@logilab.fr
-#
-# This program is free software; you can redistribute it and/or modify it under
-# the terms of the GNU General Public License as published by the Free Software
-# Foundation; either version 2 of the License, or (at your option) any later
-# version.
-#
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details
-#
-# You should have received a copy of the GNU General Public License along with
-# this program; if not, write to the Free Software Foundation, Inc.,
-# 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
-""" Universal report objects and some formatting drivers
-
-a way to create simple reports using python objects, primarly designed to be
-formatted as text and html
-"""
+"""Universal report objects and some formatting drivers.
+
+A way to create simple reports using python objects, primarly designed to be
+formatted as text and html.
+
+:copyright:
+  2004-2008 `LOGILAB S.A. <http://www.logilab.fr>`_ (Paris, FRANCE),
+  all rights reserved.
 
+:contact:
+  http://www.logilab.org/project/logilab-common --
+  mailto:python-projects@logilab.org
+
+:license:
+  `General Public License version 2
+  <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>`_
+"""
 from __future__ import generators
+__docformat__ = "restructuredtext en"
 
 import sys
 from cStringIO import StringIO
diff --git a/ureports/docbook_writer.py b/ureports/docbook_writer.py
index 5ce5760..fe8fc79 100644
--- a/ureports/docbook_writer.py
+++ b/ureports/docbook_writer.py
@@ -1,22 +1,19 @@
-# Copyright (c) 2002-2004 LOGILAB S.A. (Paris, FRANCE).
-# http://www.logilab.fr/ -- mailto:contact@logilab.fr
-#
-# This program is free software; you can redistribute it and/or modify it under
-# the terms of the GNU General Public License as published by the Free Software
-# Foundation; either version 2 of the License, or (at your option) any later
-# version.
-#
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details
-#
-# You should have received a copy of the GNU General Public License along with
-# this program; if not, write to the Free Software Foundation, Inc.,
-# 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
-"""HTML formatting drivers for ureports
-"""
+"""HTML formatting drivers for ureports.
+
+:copyright:
+  2004-2008 `LOGILAB S.A. <http://www.logilab.fr>`_ (Paris, FRANCE),
+  all rights reserved.
 
-__revision__ = "$Id: docbook_writer.py,v 1.4 2005-05-20 16:42:23 emb Exp $"
+:contact:
+  http://www.logilab.org/project/logilab-common --
+  mailto:python-projects@logilab.org
+
+:license:
+  `General Public License version 2
+  <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>`_
+"""
+from __future__ import generators
+__docformat__ = "restructuredtext en"
 
 from logilab.common.ureports import HTMLWriter
 
diff --git a/ureports/html_writer.py b/ureports/html_writer.py
index 33506d0..460ec05 100644
--- a/ureports/html_writer.py
+++ b/ureports/html_writer.py
@@ -1,22 +1,18 @@
-# Copyright (c) 2004-2005 LOGILAB S.A. (Paris, FRANCE).
-# http://www.logilab.fr/ -- mailto:contact@logilab.fr
-#
-# This program is free software; you can redistribute it and/or modify it under
-# the terms of the GNU General Public License as published by the Free Software
-# Foundation; either version 2 of the License, or (at your option) any later
-# version.
-#
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details
-#
-# You should have received a copy of the GNU General Public License along with
-# this program; if not, write to the Free Software Foundation, Inc.,
-# 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
-"""HTML formatting drivers for ureports
-"""
+"""HTML formatting drivers for ureports.
+
+:copyright:
+  2004-2008 `LOGILAB S.A. <http://www.logilab.fr>`_ (Paris, FRANCE),
+  all rights reserved.
 
-__revision__ = "$Id: html_writer.py,v 1.10 2006-03-08 09:47:29 katia Exp $"
+:contact:
+  http://www.logilab.org/project/logilab-common --
+  mailto:python-projects@logilab.org
+
+:license:
+  `General Public License version 2
+  <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>`_
+"""
+__docformat__ = "restructuredtext en"
 
 from cgi import escape
 
diff --git a/ureports/nodes.py b/ureports/nodes.py
index c8da4f5..3807a4c 100644
--- a/ureports/nodes.py
+++ b/ureports/nodes.py
@@ -1,25 +1,19 @@
-# This program is free software; you can redistribute it and/or modify it under
-# the terms of the GNU General Public License as published by the Free Software
-# Foundation; either version 2 of the License, or (at your option) any later
-# version.
-#
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details
-#
-# You should have received a copy of the GNU General Public License along with
-# this program; if not, write to the Free Software Foundation, Inc.,
-# 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
-"""Micro reports objects
-
-A micro report is a tree of layout and content objects
-
-
-:author:    Logilab
-:copyright: 2004-2008 LOGILAB S.A. (Paris, FRANCE)
-:contact:   http://www.logilab.fr/ -- mailto:python-projects@logilab.org
-"""
+"""Micro reports objects.
+
+A micro report is a tree of layout and content objects.
+
+:copyright:
+  2004-2008 `LOGILAB S.A. <http://www.logilab.fr>`_ (Paris, FRANCE),
+  all rights reserved.
 
+:contact:
+  http://www.logilab.org/project/logilab-common --
+  mailto:python-projects@logilab.org
+
+:license:
+  `General Public License version 2
+  <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>`_
+"""
 __docformat__ = "restructuredtext en"
 
 from logilab.common.tree import VNode
diff --git a/ureports/text_writer.py b/ureports/text_writer.py
index 6e03f6b..437d88b 100644
--- a/ureports/text_writer.py
+++ b/ureports/text_writer.py
@@ -1,19 +1,18 @@
-# Copyright (c) 2004-2005 LOGILAB S.A. (Paris, FRANCE).
-# http://www.logilab.fr/ -- mailto:contact@logilab.fr
-#
-# This program is free software; you can redistribute it and/or modify it under
-# the terms of the GNU General Public License as published by the Free Software
-# Foundation; either version 2 of the License, or (at your option) any later
-# version.
-#
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-# FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details
-#
-# You should have received a copy of the GNU General Public License along with
-# this program; if not, write to the Free Software Foundation, Inc.,
-# 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
-"""Text formatting drivers for ureports"""
+"""Text formatting drivers for ureports.
+
+:copyright:
+  2004-2008 `LOGILAB S.A. <http://www.logilab.fr>`_ (Paris, FRANCE),
+  all rights reserved.
+
+:contact:
+  http://www.logilab.org/project/logilab-common --
+  mailto:python-projects@logilab.org
+
+:license:
+  `General Public License version 2
+  <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>`_
+"""
+__docformat__ = "restructuredtext en"
 
 from logilab.common.textutils import linesep
 from logilab.common.ureports import BaseWriter