apply tahiti team doc patch

4 files changed, 309 insertions, 144 deletions

diff --git a/doc/FAQ.txt b/doc/FAQ.txt
index 9fa496c..b48d95f 100644
--- a/doc/FAQ.txt
+++ b/doc/FAQ.txt
@@ -1,186 +1,329 @@
+==========================
 Frequently Asked Questions
 ==========================
 
+.. contents::
 
-Question:
-  Is it possible to give file as argument to pylint, instead of module ?
+1. About Pylint
+===============
 
-Answer:
-  pylint expects the name of a package or module as argument. As a convenience,
-  you can give to it a file name if it's possible to guess a module name from
-  the file's path, using the python path. Some examples :
+1.1 What is Pylint?
+--------------------
 
-  "pylint mymodule.py" should always works since the current working
-  directory is automatically added on top  of the python path
+Pylint is a `static code checker`_, meaning it can analyse your code without
+actually running it. Pylint checks for errors, tries to enforce a coding
+standard, and tries to enforce a coding style.
 
-  "pylint directory/mymodule.py" will work if "directory" is a python
-  package (i.e. has an __init__.py file) or if "directory" is in the
-  python path.
+.. _`static code checker`: http://en.wikipedia.org/wiki/Static_code_analysis
 
-  "pylint /whatever/directory/mymodule.py" will work if either:
+1.2 How is Pylint different from Pychecker?
+-------------------------------------------
 
-    - "/whatever/directory" is in the python path
+A major difference between Pylint and Pychecker_ is that Pylint checks for
+style issues, while Pychecker explicitly does not. There are a few other
+differences, such as the fact that Pylint does not import live modules while
+Pychecker does (see `6.2 Why does Pychecker catch problems with imports that 
+Pylint doesn't?`_).
 
-    - your cwd is "/whatever/directory"
+1.3 Who wrote Pylint?
+---------------------
 
-    - "directory" is a python package and "/whatever" is in the python
-      path
+Pylint's main author and maintainer is Sylvain Thénault. Pylint's development
+is funded by Logilab_. For a full list of contributors, see the "Contributors"
+section of Pylint's README file.
 
-    - "directory" is a python package and your cwd is "/whatever"
-      and so on...
+.. _Logilab: http://www.logilab.fr/
 
+1.4 Who uses Pylint?
+--------------------
 
+In addition to many individuals, the following projects are known to use pylint 
+to help develop better
+code: 
 
-Question:
-  I'm using psyobj from psyco_ and get a lot of spurious "unused variables
-  messages". Is it normal ?
+* OSAF Chandler (http://www.osafoundation.org/)
+* Xen (http://www.xensource.com/)
+* CPS (http://www.nuxeo.org)
+* ERP5 (http://www.erp5.org/)
+* pyxmpp (http://pyxmpp.jabberstudio.org/)
+* mercurial 
+* eXe (http://exelearning.org/)
+* PrimaGIS (http://www.primagis.org)
+* python-cdd (http://projetos.ossystems.com.br/python-cdd/)
+* CDSWare (http://cdsware.cern.ch/)
+* ASE (http://dcwww.camp.dtu.dk/campos/ASE/intro.html)
+* RunJob (http://projects.fnal.gov/runjob/)
+* Slugathon (http://slugathon.python-hosting.com/)
+* Topographica (http://topographica.org/Home/index.html) (at least 
+  they intend to do so)
+* http://browsershots.org 
 
-Answer: 
-  Yes. That's actually due to a bug in psyco, making the locals()
-  function for objects inheriting from *psyobj* returning an empty
-  dictionary. For the moment, the only way to fix this is to use the
-  PYLINT_IMPORT environment variable to not use psyco during pylint
-  checking. Sample code ::
 
-    import os
-    try:
-        if os.environ.has_key('PYLINT_IMPORT'):
-            raise ImportError()
-	from psyco.classes import psyobj
-    except ImportError:
-	    class psyobj:
-	        pass
+2. Installation
+===============
 
-  NOTICE: this problem should not occurs with pylint >= 0.5 since from
-  this version pylint is not looking anymore for information in living
-  objects (i.e. it doesn't anymore import analysed modules)
+2.1 How do I install Pylint?
+----------------------------
 
+The easiest way to install Pylint, if you have the setuptools_ package, is to 
+invoke ::
 
+    easy_install pylint
 
-Question:
-  I've a function / method which is a callback where I do not have any
-  control on received argument, and pylint is complaining about unused
-  arguments. What can I do to avoid those warnings ?
+Otherwise, you'll have to download the source for Pylint and its dependencies 
+from the Logilab site, or through Pylint's repository. See the user manual for 
+detailed installation instructions.
 
-Answer:
-  prefix (ui) the callback's name by `cb_`, as in cb_onclick(...). By
-  doing so arguments usage won't be checked. Another solution is to
-  use one of the name defined in the "dummy-variables" configuration
-  variable for unused argument ("_" and "dummy" by default).
+.. _setuptools: http://pypi.python.org/pypi/setuptools
 
+2.2 What kind of versioning system does Pylint use?
+---------------------------------------------------
 
+Pylint uses the Mercurial_ distributed version control system. The URL of the 
+repository is:	http://www.logilab.org/hg/pylint. To get the latest version of 
+Pylint from the repository, simply invoke ::
 
-Question:
-  When is pylint considering a class as an interface ?
+    hg clone http://www.logilab.org/hg/pylint
 
-Answer:
-  A class is considered as an interface if there is a class named
-  "Interface" somewhere in it ancestor's tree.
+.. _Mercurial: http://mercurial.selenic.com/
 
+2.3 What are Pylint's dependencies?
+-----------------------------------
 
+Pylint requires the latest `logilab-astng`_ and `logilab-common`_
+packages. It should be compatible with any python version greater than
+2.2.0.
 
-Question:
-  When is pylint considering that a class is implementing a given
-  interface ?
+.. _`logilab-astng`: http://www.logilab.org/project/name/astng
+.. _`logilab-common`: http://www.logilab.org/project/name/common
 
-Answer:
-  Pylint is using the Zope 2 interfaces conventions, and so is
-  considering that a class is implementing interfaces listed in its
-  __implements__ attribute.
 
+3. Running Pylint
+=================
 
+3.1 Can I give pylint a file as an argument instead of a module?
+-----------------------------------------------------------------
 
-Question:
-  When is pylint considering a class as an abstract class ?
+Pylint expects the name of a package or module as its argument. As a 
+convenience,
+you can give it a file name if it's possible to guess a module name from
+the file's path using the python path. Some examples :
 
-Answer:
-  A class is considered as an abstract class if at least one of its
-  methods is doing nothing but raising NotImplementedError
+"pylint mymodule.py" should always work since the current working
+directory is automatically added on top of the python path
 
+"pylint directory/mymodule.py" will work if "directory" is a python
+package (i.e. has an __init__.py file) or if "directory" is in the
+python path.
 
+"pylint /whatever/directory/mymodule.py" will work if either:
 
-Question:
-  Is there some way to disable some message for a particular module
-  only ?
+	- "/whatever/directory" is in the python path
 
-Answer:
-  Yes, you can disable or enable (globally disabled) message at the
-  module level by adding the corresponding option in a comment at the
-  top of the file: ::
+	- your cwd is "/whatever/directory"
 
-    # pylint: disable-msg=W0401, E0202
-    # pylint: enable-msg=C0302
+	- "directory" is a python package and "/whatever" is in the python	
+          path
 
+	- "directory" is a python package and your cwd is "/whatever" and so 
+          on...
 
+3.2 Where is the persistent data stored to compare between successive runs?
+----------------------------------------------------------------------------
 
-Question:
-  I have a mixin class relying on attributes of the mixed class, and I
-  would like to not have the "access to undefined member" message on
-  this class. Is it possible ?
+Analysis data are stored as a pickle file in a directory which is 
+localized using the following rules:
 
-Answer:
-  Yes :o) To do so you have to set the ignore-mixin-members option to
-  "yes" (this is the default value) and to name your mixin class with
-  a name which ends with "mixin" (whatever case)
+* value of the PYLINTHOME environment variable if set
 
+* ".pylint.d" subdirectory of the user's home directory if it is found
+	(not always findable on Windows platforms)
 
+* ".pylint.d" directory in the current directory
 
-Question:
-  Is it possible to locally disable a particular message for a block
-  of code or for a single line of code ?
-  
-Answer:
-  Yes, this feature has been added in pylint 0.11. This may be done by
-  adding "#pylint: disable-msg=W0123,E4567" at the desired block level
-  or at the end of the desired line of code
+3.3 How do I find the option name (for pylintrc) corresponding to a specific command line option?
+--------------------------------------------------------------------------------------------------------
 
+You can always generate a sample pylintrc file with --generate-rcfile
+Every option present on the command line before this will be included in
+the rc file
 
+For example::
 
-Question:
-  Where is the persistent data stored to make comparison between
-   two successive runs ?
+	pylint --disable-msg=W0702,C0103 --class-rgx='[A-Z][a-z]+' --generate-rcfile
 
-Answer:
-  Analysis data are stored as pickle file in a directory which is 
-  localized using the following rules:
+3.4 I'd rather not run Pylint from the command line. Can I integrate it with my editor?
+---------------------------------------------------------------------------------------
 
-  * value of the PYLINTHOME environment variable if set
+Yes! Pylint can be integrated with many popular editors and IDEs. The following 
+include Pylint by default:
 
-  * ".pylint.d" subdirectory of the user's home directory if it is found
-    (not always findable on Windows platforms)
+* emacs (of course)
+* eric3
+* eclipse (using the pydev_ plugin, see also
+  http://msdl.cs.mcgill.ca/MSDL/people/denis/meetings/pythonDev)
 
-  * ".pylint.d" directory in the current directory
+To use pylint from within vim, see
+http://www.gonzo.kiev.ua/projects/pylint.vim 
 
+To use pylint from within komodo_, see
+http://mateusz.loskot.net/2006/01/15/running-pylint-from-komodo/ 
 
+To use pylint from within gedit_, see
+http://live.gnome.org/Gedit/PylintPlugin
 
-Question:
-  How can I know the option name (for pylintrc) corresponding to a
-  specific command line option ?
+To use pylint from within WingIDE_, see
+http://www.wingware.com/doc/edit/pylint
 
-Answer:
-  You can always generate a sample pylintrc file with --generate-rcfile
-  Every option present on the command line before this will be included in
-  the rc file
+.. _pydev: http://pydev.sourceforge.net
+.. _komodo: http://www.activestate.com/Products/Komodo/
+.. _gedit: http://www.gnome.org/projects/gedit/
+.. _WingIDE: http://www.wingware.com/
+
+4. Message Control
+==================
+
+4.1 Is it possible to locally disable a particular message?
+-----------------------------------------------------------
   
-  For example::
+Yes, this feature has been added in pylint 0.11. This may be done by
+adding "#pylint: disable-msg=W0123,E4567" at the desired block level
+or at the end of the desired line of code
 
-    pylint --disable-msg=W0702,C0103 --class-rgx='[A-Z][a-z]+' --generate-rcfile
 
+4.2 Why do I get a lot of spurious "unused variables messages" when using psyobj from psyco_?
+----------------------------------------------------------------------------------------------
 
+This is actually due to a bug in psyco, making the locals()
+function for objects inheriting from *psyobj* returning an empty
+dictionary. For the moment, the only way to fix this is to use the
+PYLINT_IMPORT environment variable to not use psyco during pylint
+checking. Sample code ::
 
-Question:
-  pychecker_ has no problem finding the imports and reporting on problems with 
-  them, while pylint seems unable to deal with the same imports. Why ?
+	import os
+	try:
+		if os.environ.has_key('PYLINT_IMPORT'):
+			raise ImportError()
+	from psyco.classes import psyobj
+	except ImportError:
+		class psyobj:
+			pass
 
-Answer:
-  pychecker and pylint use different approaches.  pychecker
-  imports the modules and rummages around in the result, hence it sees my
-  mangled sys.path.  pylint doesn't import any of the candidate modules and
-  thus doesn't include any of import's side effects (good and bad).  It
-  traverses an AST representation of the code.
+NOTICE: this problem should not occur with pylint >= 0.5 since from
+this version pylint is not looking anymore for information in living
+objects (i.e. it no longer imports analysed modules)
 
+.. _psyco: http://psyco.sf.net
 
+4.3 I have a callback function where I have no control over received arguments. How do I avoid getting unused argument warnings?
+----------------------------------------------------------------------------------------------------------------------------------
 
+Prefix (ui) the callback's name by `cb_`, as in cb_onclick(...). By
+doing so arguments usage won't be checked. Another solution is to
+use one of the names defined in the "dummy-variables" configuration
+variable for unused argument ("_" and "dummy" by default).
+
+4.4 Is there a way to disable a message for a particular module only?
+---------------------------------------------------------------------
+
+Yes, you can disable or enable (globally disabled) messages at the
+module level by adding the corresponding option in a comment at the
+top of the file: ::
+
+	# pylint: disable-msg=W0401, E0202
+	# pylint: enable-msg=C0302
+
+5. Classes and Inheritance
+==========================
+
+5.1 When is pylint considering a class as an interface?
+-------------------------------------------------------
+
+A class is considered as an interface if there is a class named "Interface" 
+somewhere in its inheritance tree.
+
+5.2 When is pylint considering that a class is implementing a given interface?
+--------------------------------------------------------------------------------
+
+Pylint is using the Zope 2 interfaces conventions, and so is
+considering that a class is implementing interfaces listed in its
+__implements__ attribute.
+
+
+5.3 When is pylint considering a class as an abstract class?
+-------------------------------------------------------------
+
+A class is considered as an abstract class if at least one of its
+methods is doing nothing but raising NotImplementedError.
+
+5.4 How do I avoid "access to undefined member" messages in my mixin classes?
+-------------------------------------------------------------------------------
+
+To do so you have to set the ignore-mixin-members option to
+"yes" (this is the default value) and to name your mixin class with
+a name which ends with "mixin" (whatever case).
+
+
+6. Troubleshooting
+==================
+
+6.1 Pylint gave my code a negative rating out of ten. That can't be right!
+--------------------------------------------------------------------------
+
+Even though the final rating Pylint renders is nominally out of ten, there's no 
+lower bound on it. By default, the formula to calculate score is ::
+
+    10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10)
+
+However, this option can be changed in the pylint rc file. If having negative 
+values really bugs you, you can set the formula to be the minimum of 0 and the 
+above expression.
+
+
+6.2 Why does Pychecker catch problems with imports that Pylint doesn't?
+------------------------------------------------------------------------
+
+pychecker and pylint use different approaches.  pychecker
+imports the modules and rummages around in the result, hence it sees my
+mangled sys.path.  pylint doesn't import any of the candidate modules and
+thus doesn't include any of import's side effects (good and bad).  It
+traverses an AST representation of the code.
+
+6.3 I think I found a bug in Pylint. What should I do?
+-------------------------------------------------------
+
+First, you might wish to check Pylint's ticketing system (the 'Tickets' tab at 
+http://www.logilab.org/project/pylint), to make sure it hasn't been reported 
+already. If it hasn't, please send a bug report to python-projects@logilab.org.
+
+Notice that if you don't find something you have expected in pylint's
+tracker page, it may be on the tracker page of one of its dependencies, namely
+astng and common:
+
+* http://www.logilab.org/project/name/logilab-astng
+* http://www.logilab.org/project/name/logilab-common
+
+6.4 I have a question about Pylint that isn't answered here.
+------------------------------------------------------------
+
+The python-projects@logilab.org mailing list is a great place to discuss and 
+ask questions about Pylint. This is a 
+moderated mailing list, so if you're not subscribed email you send will have to
+be validated first before actually being sent on the list.
+
+You can subscribe to this mailing list at
+http://lists.logilab.org/mailman/listinfo/python-projects
+
+Archives are available at 
+http://lists.logilab.org/pipermail/python-projects/
+
+If you prefer speaking french instead of english, you can use the
+generic forum-fr@logilab.org mailing list:
+
+* (un)subscribe: http://lists.logilab.org/mailman/listinfo/forum-fr
+* archives: http://lists.logilab.org/pipermail/forum-fr
+
+Notice though that this list has a very low traffic since most pylint related
+discussions are done on the python-projects mailing list. 
 
-.. _psyco: http://psyco.sf.net
 .. _pychecker: http://pychecker.sf.net
diff --git a/doc/beginner_pylint_tutorial.txt b/doc/beginner_pylint_tutorial.txt
index 589de97..b751d3a 100644
--- a/doc/beginner_pylint_tutorial.txt
+++ b/doc/beginner_pylint_tutorial.txt
@@ -19,7 +19,7 @@ in open source.  Whatever the motivation, your good intentions may not have the
 desired outcome if people find your code hard to use or understand.  The Python
 community has formalized some recommended programming styles to help everyone 
 write code in a common, agreed-upon style that makes the most sense for shared 
-code.  This style is captured in PEP-8.  Pylint can be a quick and easy way of 
+code.  This style is captured in PEP-8_.  Pylint can be a quick and easy way of 
 seeing if your code has captured the essence of PEP-8 and is therefore 
 'friendly' to other potential users.
 
@@ -36,6 +36,8 @@ My command line prompt for these examples is: ::
 
   robertk01 Desktop$
 
+.. _PEP-8: http://www.python.org/dev/peps/pep-0008/
+
 Getting Started
 ---------------
 
@@ -90,7 +92,7 @@ Your First Pylint'ing
 
 We'll use a basic python script as fodder for our tutorial.  I borrowed 
 extensively from the code here: http://www.daniweb.com/code/snippet748.html
-The starting code we will use is called simplecaeser.py and is here in it's 
+The starting code we will use is called simplecaeser.py and is here in its 
 entirety: ::
 
    1  #!/usr/bin/env python
@@ -246,6 +248,10 @@ what rule I violated.  Knowing only that I violated a convention isn't much help
 if I'm a newbie.  So let's turn on a bit more info by using the option 
 "--include-ids=y".
 
+.. tip:: Many of Pylint's commonly used command line options have shortcuts.
+ for example, "--reports=n" can be abbreviated to "-r n", and "--include-ids=y"
+ can be abbreviated to "-i y". Pylint's man page lists all these shortcuts.
+
 Let's do it again! ::
 
   robertk01 Desktop$ pylint --reports=n --include-ids=y simplecaeser.py 
@@ -364,13 +370,17 @@ will now be quite quiet: ::
   No config file found, using default configuration
 
 Regular expressions can be quite a beast so take my word on this particular 
-example but go ahead and read up on them if you want.
+example but go ahead and `read up`_ on them if you want.
 
-It would really be a pain in the butt to have to use all these options on the 
-command line all the time.  That's what the rc file is for.  We can configure
-our Pylint to store our options for us so we don't have to declare them on the 
-command line.  Using the rc file is a nice way of formalizing your rules and 
-quickly sharing them with others and/or forcing your style on them.  Go ahead, 
-conquer the standards world by spreading your rc file...I dare you.
+.. tip::
+ It would really be a pain in the butt to have to use all these options
+ on the command line all the time.  That's what the rc file is for.  We can
+ configure our Pylint to store our options for us so we don't have to declare 
+ them on the command line.  Using the rc file is a nice way of formalizing your
+ rules and quickly sharing them with others. Invoking 'pylint
+ --generate-rcfile' will create a sample rcfile with all the options set and
+ explained in comments.
 
 That's it for the basic intro.  More tutorials will follow.
+
+.. _`read up`: http://docs.python.org/library/re.html
diff --git a/doc/manual.txt b/doc/manual.txt
index c82bbc5..b92da31 100644
--- a/doc/manual.txt
+++ b/doc/manual.txt
@@ -62,11 +62,10 @@ Dependencies
 ''''''''''''
 Pylint requires the latest `logilab-astng`_ and `logilab-common`_
 packages. It should be compatible with any python version greater than
-2.2.0 (python 2.2 users will have to install the optik_ package).
+2.2.0.
 
 .. _`logilab-astng`: http://www.logilab.org/project/name/astng
 .. _`logilab-common`: http://www.logilab.org/project/name/common
-.. _optik: http://optik.sourceforge.net/
 
 
 Distributions
@@ -113,7 +112,7 @@ On Windows, once you have installed pylint, the command line usage is ::
 But this will only work if *pylint.bat* is either in the current
 directory, or on your system path. (*setup.py* install install *python.bat*
 to the *Scripts* subdirectory of your Python installation -- e.g.
-C:\Python24\Scripts.) You can do any of the following to solve this:
+C:/Python24/Scripts.) You can do any of the following to solve this:
 
 1. change to the appropriate directory before running pylint.bat
 
@@ -138,10 +137,10 @@ line without the .bat, just as do non-Windows users by typing: ::
 To effect option (3), simply create a plain text file pylint.bat with
 the single line: ::
 
-  C:\PythonDirectory\Scripts\pylint.bat
+  C:/PythonDirectory/Scripts/pylint.bat
 
 (where PythonDirectory is replaced by the actual Python installation
-directory on your system -- e.g. C:\Python24\Scripts\pylint.bat).
+directory on your system -- e.g. C:/Python24/Scripts/pylint.bat).
 
 
 Invoking pylint
@@ -171,7 +170,7 @@ directory is automatically added on top of the python path ::
 will work if "directory" is a python package (i.e. has an __init__.py
 file) or if "directory" is in the python path.
 
-For more details on this see the `Frequently Asked Questions`_.
+For more details on this see the Frequently Asked Questions.
 
 You can also start a thin gui around pylint (require TkInter) by
 typing ::
@@ -183,7 +182,7 @@ or module to check, at pylint messages will be displayed in the user
 interface.
 
 It is also possible to call Pylint from an other Python program,
-thanks ``py_run()`` function in ``lint`` module,
+thanks to ``py_run()`` function in ``lint`` module,
 assuming Pylint options are stored in ``pylint_options`` string, as ::
 
   from pylint import lint
@@ -200,7 +199,7 @@ Pylint output
 -------------
 
 The default format for the output is raw text. But passing pylint the
-``--output-format=html`` option will produce an HTML document.
+``--output-format=html`` or ``-h y`` or ``-o html`` option will produce an HTML document.
 
 There are several sections in pylint's output. 
 
@@ -589,8 +588,25 @@ http://www.logilab.org/src/logilab/common
 
 .. _mercurial: http://www.selenic.com/mercurial/
 
-
-
+Contribution Instructions
+--------------------------
+Got a patch for pylint?  There a few steps you must take to make sure your 
+patch gets accepted.
+
+* Test your code
+    * Pylint keeps a set of unit tests in the /test directory. To get your 
+      patch accepted you must write (or change) a test input file and message 
+      file in the appropriate input and messages folders. 
+    * In the test folder of pylint run ./fulltest.sh (python version), make sure
+      all tests pass before submitting a patch
+* Create a diff file
+    * To create a diff from the command line invoke (from a directory under
+      version control) ::
+
+            hg diff  > <yourname>.diff
+    
+* E-mail the mailing list with your diff file
+      
 Other information
 =================
 
@@ -633,7 +649,7 @@ code:
 * mercurial 
 * eXe (http://exelearning.org/)
 * PrimaGIS (http://www.primagis.org)
-* python-cdd (http://projetos.ossystems.com.br/python-cdd/)
+* python-cdd (https://projetos.ossystems.com.br/projects/python-cdd)
 * CDSWare (http://cdsware.cern.ch/)
 * ASE (http://dcwww.camp.dtu.dk/campos/ASE/intro.html)
 * RunJob (http://projects.fnal.gov/runjob/)
@@ -649,8 +665,4 @@ analyze the source code.
 
 
 
-.. include:: FAQ.txt
-
-
-
 
diff --git a/doc/quickstart.txt b/doc/quickstart.txt
index 1915678..3e9fd62 100644
--- a/doc/quickstart.txt
+++ b/doc/quickstart.txt
@@ -19,7 +19,7 @@ What is pylint?
 ---------------
 
 Pylint is a tool that checks for errors in python code, tries to
-enforce a coding standard and looks for smelling code . This is
+enforce a coding standard and looks for bad code smells. This is
 similar but nevertheless different from what pychecker_ provides,
 especially since pychecker explicitly does not bother with coding
 style. The default coding style used by pylint is close to 
@@ -81,7 +81,7 @@ Pylint output
 -------------
 
 The default format for the output is raw text. But passing pylint the
-``--output-format=html`` option will produce an HTML document.
+``--output-format=html`` or ``-f html`` option will produce an HTML document.
 
 There are several sections in pylint's output.