[doc] complete refactoring

1 files changed, 354 insertions, 0 deletions

diff --git a/doc/faq.rst b/doc/faq.rst
new file mode 100644
index 0000000..dbe8aae
--- /dev/null
+++ b/doc/faq.rst
@@ -0,0 +1,354 @@
+.. -*- coding: utf-8 -*-
+
+==========================
+Frequently Asked Questions
+==========================
+
+1. About Pylint
+===============
+
+1.1 What is Pylint?
+--------------------
+
+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.
+
+.. _`static code checker`: http://en.wikipedia.org/wiki/Static_code_analysis
+
+1.2 How is Pylint different from Pychecker?
+-------------------------------------------
+
+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?`_).
+
+1.3 Who wrote Pylint?
+---------------------
+
+Pylint's main author and maintainer for the first ten years of its life has been
+Sylvain Thénault, while he worked at Logilab_ where the project was born. For a
+full list of contributors, see the "Contributors" section of Pylint's README
+file.
+
+.. _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 write better code:
+
+* 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
+
+
+2. Installation
+===============
+
+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
+
+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.
+
+.. _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:	https://bitbucket.org/logilab/pylint. To get the latest version of
+Pylint from the repository, simply invoke ::
+
+    hg clone https://bitbucket.org/logilab/pylint
+
+.. _Mercurial: http://mercurial.selenic.com/
+
+2.3 What are Pylint's dependencies?
+-----------------------------------
+
+Pylint requires the latest `astng`_ and `logilab-common`_ packages. It should be
+compatible with any python version greater than 2.5.0.
+
+.. _`astng`: https://bitbucket.org/logilab/astng
+.. _`logilab-common`: http://www.logilab.org/project/logilab-common
+
+
+3. Running Pylint
+=================
+
+3.1 Can I give pylint a file as an argument instead of a module?
+-----------------------------------------------------------------
+
+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 :
+
+"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:
+
+	- "/whatever/directory" is in the python path
+
+	- your cwd is "/whatever/directory"
+
+	- "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?
+----------------------------------------------------------------------------
+
+Analysis data are stored as a pickle file in a directory which is
+localized using the following rules:
+
+* 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
+
+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::
+
+	pylint --disable=W0702,C0103 --class-rgx='[A-Z][a-z]+' --generate-rcfile
+
+3.4 I'd rather not run Pylint from the command line. Can I integrate it with my editor?
+---------------------------------------------------------------------------------------
+
+Yes! Pylint can be integrated with many popular editors and IDEs. The following
+include Pylint by default:
+
+* emacs (of course)
+* eric3
+* eclipse (using the pydev_ plugin, see also
+  http://msdl.cs.mcgill.ca/MSDL/people/denis/meetings/pythonDev)
+
+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
+
+To use pylint from within WingIDE_, see
+http://www.wingware.com/doc/edit/pylint
+
+.. _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?
+-----------------------------------------------------------
+
+Yes, this feature has been added in pylint 0.11. This may be done by
+adding "#pylint: disable=W0123,E4567" at the desired block level
+or at the end of the desired line of code
+
+
+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 ::
+
+	import os
+	try:
+		if os.environ.has_key('PYLINT_IMPORT'):
+			raise ImportError()
+	from psyco.classes import psyobj
+	except ImportError:
+		class psyobj:
+			pass
+
+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=W0401, E0202
+	# pylint: enable=C0302
+
+4.5 What is the format of the configuration file?
+---------------------------------------------------
+
+Pylint uses ConfigParser from the standard library to parse the configuration file.
+It means that if you need to disable a lot of messages, you can use tricks like: ::
+
+    disable= W0401, # because I do not want it
+     E0202, # I have a good reason, trust me
+     C0302  # that's it
+
+4.6 Do I have to remember all these numbers?
+--------------------------------------------
+
+No, starting from 0.25.3, you can use symbolic names for messages::
+
+    # pylint: disable=fixme, line-too-long
+
+You can show these symbols in the output with the `-sy` option.
+
+4.7 How can I tell Pylint to never check a given module?
+--------------------------------------------------------
+
+With Pylint < 0.25, add "#pylint: disable-all" at the beginning of the
+module. Pylint 0.26.1 and up have renamed that directive to
+"#pylint: skip-file" (but the first version will be kept for backward
+compatibility).
+
+In order to ease finding which modules are ignored a Information-level
+message I0013 is emited. With recent versions of Pylint, if you use
+the old syntax, an additional I0014 message is emited.
+
+
+
+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 'Issues' tab at
+https://bitbucket.org/logilab/pylint), to make sure it hasn't been reported
+already. If it hasn't, please create a new issue there.
+
+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.
+
+.. _pychecker: http://pychecker.sf.net