[doc] complete refactoring

14 files changed, 782 insertions, 79 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 71bb241..52a24bf 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -36,7 +36,7 @@ help:
 clean:
 	-rm -rf $(BUILDDIR)/*
 
-html:
+html: features.rst
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
@@ -128,3 +128,26 @@ doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
+
+
+features.rst:
+	chmod u+w ${SRC}/features.txt
+	echo "PyLint features" > ${SRC}/features.txt
+	echo "===============" >> ${SRC}/features.txt
+	echo "" >> ${SRC}/features.txt
+	echo ".. generated by pylint --full-documentation" >> ${SRC}/features.txt
+	echo "" >> ${SRC}/features.txt
+	echo ".. contents::" >> ${SRC}/features.txt
+	echo "" >> ${SRC}/features.txt
+	pylint --full-documentation >> ${SRC}/features.txt
+	${MKHTML} ${MKHTML_OPT} ${SRC}/features.txt
+
+gen-examples:
+	chmod u+w ../examples/pylintrc
+	pylint --generate-rcfile > ../examples/pylintrc
+
+gen-man:
+	chmod u+w ../man/pylint.1
+	pylint --generate-man > ../man/pylint.1
+
+all: html gen-man gen-examples
\ No newline at end of file
diff --git a/doc/backlinks.rst b/doc/backlinks.rst
new file mode 100644
index 0000000..8fc42be
--- /dev/null
+++ b/doc/backlinks.rst
@@ -0,0 +1,27 @@
+
+Some projects using Pylint
+--------------------------
+The following projects are known to use Pylint to help develop 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 (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/)
+* Slugathon (http://slugathon.python-hosting.com/)
+* Topographica (http://topographica.org/Home/index.html) (at least they intend to do so)
+* http://browsershots.org
+* many more...
+
+Also notice that the CheeseCake_ kwalitee reporting tool uses Pylint to
+analyze the source code.
+
+.. _CheeseCake: http://cheesecake.sourceforge.net/
diff --git a/doc/contribute.rst b/doc/contribute.rst
new file mode 100644
index 0000000..762e351
--- /dev/null
+++ b/doc/contribute.rst
@@ -0,0 +1,83 @@
+.. -*- coding: utf-8 -*-
+
+============
+ Contribute
+============
+
+Bug reports, feedback
+---------------------
+
+You think you have found a bug in Pylint? Well, this may be the case
+since Pylint is under development. Please take the time to send a bug
+report to python-projects@logilab.org if you've not found it already reported on
+the `tracker page`_. This mailing list is also a nice place to
+discuss Pylint issues, see below for more information about Pylint's related
+lists.
+
+You can check for already reported bugs, planned features on Pylint's tracker
+web page: http://www.logilab.org/project/pylint
+
+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/logilab-astng
+* http://www.logilab.org/project/logilab-common
+
+.. _`tracker page`: http://www.logilab.org/project/pylint
+
+Mailing lists
+-------------
+
+Use the python-projects@logilab.org mailing list for anything related
+to Pylint. This is in most cases better than sending an email directly
+to the author, since others will benefit from the exchange, and you'll
+be more likely answered by someone subscribed to the list. 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.
+
+
+Forge
+-----
+
+Pylint is developped using the mercurial_ distributed version control system.
+
+You can clone Pylint and its dependencies from ::
+
+  hg clone http://www.logilab.org/src/pylint
+  hg clone http://www.logilab.org/src/logilab/astng
+  hg clone http://www.logilab.org/src/logilab/common
+
+.. _mercurial: http://www.selenic.com/mercurial/
+
+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 versions>``, 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
diff --git a/doc/extend.rst b/doc/extend.rst
new file mode 100644
index 0000000..640ad68
--- /dev/null
+++ b/doc/extend.rst
@@ -0,0 +1,37 @@
+
+Extending Pylint
+================
+
+Writing your own checker
+------------------------
+You can find some simple examples in the examples
+directory of the distribution (custom.py and custom_raw.py). I'll try to
+quickly explain the essentials here.
+
+First, there are two kinds of checkers :
+* raw checkers, which are analysing each module as a raw file stream
+* ast checkers, which are working on an ast representation of the module
+
+The ast representation used is an extension of the one provided with the
+standard Python distribution in the `compiler package`_. The extension
+adds additional information and methods on the tree nodes to ease
+navigation and code introspection.
+
+An AST checker is a visitor, and should implement
+visit_<lowered class name>
+leave_<lowered class name>
+methods for the nodes it's interested in. To get description of the different
+classes used in an ast tree, look at the `compiler.ast documentation`.
+Checkers are ordered by priority. For each module, Pylint's engine:
+
+1. give the module source file as a stream to raw checkers
+2. get an ast representation for the module
+3. make a depth first descent of the tree, calling visit_<> on each AST
+   checker when entering a node, and living_<> on the back traversal
+
+Notice that the source code is probably the best source of
+documentation, it should be clear and well documented. Don't hesitate to
+ask for any information on the python-projects mailing list.
+
+.. _`compiler package`: http://docs.python.org/library/compiler
+.. _`compiler.ast documentation`: http://docs.python.org/library/compiler#module-compiler.ast
diff --git a/doc/FAQ.rst b/doc/faq.rst
index e2bb213..dbe8aae 100644
--- a/doc/FAQ.rst
+++ b/doc/faq.rst
@@ -1,11 +1,9 @@
-.. class:: article
+.. -*- coding: utf-8 -*-
 
 ==========================
 Frequently Asked Questions
 ==========================
 
-.. contents::
-
 1. About Pylint
 ===============
 
@@ -30,18 +28,18 @@ Pylint doesn't?`_).
 1.3 Who wrote Pylint?
 ---------------------
 
-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.
+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 better
-code:
+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/)
@@ -198,7 +196,7 @@ or at the end of the desired line of code
 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
+PYLINT_IMPORT environment variable to not use psyco during Pylint
 checking. Sample code ::
 
 	import os
@@ -210,8 +208,8 @@ checking. Sample code ::
 		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
+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
@@ -237,7 +235,7 @@ top of the file: ::
 4.5 What is the format of the configuration file?
 ---------------------------------------------------
 
-pylint uses ConfigParser from the standard library to parse 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
@@ -256,7 +254,7 @@ 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
+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).
@@ -270,13 +268,13 @@ the old syntax, an additional I0014 message is emited.
 5. Classes and Inheritance
 ==========================
 
-5.1 When is pylint considering a class as an interface?
+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?
+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
@@ -284,7 +282,7 @@ considering that a class is implementing interfaces listed in its
 __implements__ attribute.
 
 
-5.3 When is pylint considering a class as an abstract class?
+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
@@ -309,7 +307,7 @@ 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
+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.
 
@@ -317,9 +315,9 @@ above expression.
 6.2 Why does Pychecker catch problems with imports that Pylint doesn't?
 ------------------------------------------------------------------------
 
-pychecker and pylint use different approaches.  pychecker
+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
+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.
 
@@ -350,7 +348,7 @@ 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
+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
diff --git a/doc/ide-integration.rst b/doc/ide-integration.rst
new file mode 100644
index 0000000..5645c1a
--- /dev/null
+++ b/doc/ide-integration.rst
@@ -0,0 +1,106 @@
+
+=================
+ IDE integration
+=================
+
+To use Pylint with Emacs, see http://www.emacswiki.org/emacs/PythonProgrammingInEmacs#toc8
+
+To use Pylint with Vim, see
+http://www.vim.org/scripts/script.php?script_id=891
+
+To use Pylint with Eclipse, see http://pydev.org
+
+To use Pylint with Komodo_, see
+http://mateusz.loskot.net/2006/01/15/running-pylint-from-komodo/
+
+To use Pylint with gedit_, see
+http://live.gnome.org/Gedit/PylintPlugin
+
+To use Pylint with WingIDE_, see
+http://www.wingware.com/doc/edit/pylint
+
+Pylint is integrated in Eric_ IDE, see the `Project > Check` menu.
+
+Pylint is integrated in Spyder_, see http://packages.python.org/spyder/pylint.html
+
+Pylint is integrated in pyscripter_, see the `Tool -> Tools` menu.
+
+.. _Eric: http://eric-ide.python-projects.org/
+.. _pyscripter: http://code.google.com/p/pyscripter/
+.. _pydev: http://pydev.org
+.. _Komodo: http://www.activestate.com/Products/Komodo/
+.. _gedit: http://www.gnome.org/projects/gedit/
+.. _WingIDE: http://www.wingware.com/
+.. _spyder: http://code.google.com/p/spyderlib/
+
+Using Pylint thru flymake in Emacs
+==================================
+
+To enable flymake for Python, insert the following into your .emacs:
+
+.. sourcecode:: common-lisp
+
+    ;; Configure flymake for Python
+    (setq pylint "epylint")
+    (when (load "flymake" t)
+      (defun flymake-pylint-init ()
+        (let* ((temp-file (flymake-init-create-temp-buffer-copy
+                           'flymake-create-temp-inplace))
+               (local-file (file-relative-name
+                            temp-file
+                            (file-name-directory buffer-file-name))))
+          (list (expand-file-name pylint "") (list local-file))))
+      (add-to-list 'flymake-allowed-file-name-masks
+                   '("\\.py\\'" flymake-pylint-init)))
+
+    ;; Set as a minor mode for Python
+    (add-hook 'python-mode-hook '(lambda () (flymake-mode)))
+
+Above stuff is in pylint/elisp/pylint-flymake.el, which should be automatically
+installed on Debian systems, in which cases you don't have to put it in your .emacs file.
+
+Other things you may find useful to set:
+
+.. sourcecode:: common-lisp
+
+    ;; Configure to wait a bit longer after edits before starting
+    (setq-default flymake-no-changes-timeout '3)
+
+    ;; Keymaps to navigate to the errors
+    (add-hook 'python-mode-hook '(lambda () (define-key python-mode-map "\C-cn" 'flymake-goto-next-error)))
+    (add-hook 'python-mode-hook '(lambda () (define-key python-mode-map "\C-cp" 'flymake-goto-prev-error)))
+
+
+Finally, by default flymake only displays the extra information about the error when you
+hover the mouse over the highlighted line. The following will use the minibuffer to display
+messages when you the cursor is on the line.
+
+.. sourcecode:: common-lisp
+
+    ;; To avoid having to mouse hover for the error message, these functions make flymake error messages
+    ;; appear in the minibuffer
+    (defun show-fly-err-at-point ()
+      "If the cursor is sitting on a flymake error, display the message in the minibuffer"
+      (require 'cl)
+      (interactive)
+      (let ((line-no (line-number-at-pos)))
+        (dolist (elem flymake-err-info)
+          (if (eq (car elem) line-no)
+    	  (let ((err (car (second elem))))
+    	    (message "%s" (flymake-ler-text err)))))))
+
+    (add-hook 'post-command-hook 'show-fly-err-at-point)
+
+
+Alternative, if you only wish to pollute the minibuffer after an explicit flymake-goto-* then use
+the following instead of a post-command-hook
+
+.. sourcecode:: common-lisp
+
+    (defadvice flymake-goto-next-error (after display-message activate compile)
+      "Display the error in the mini-buffer rather than having to mouse over it"
+      (show-fly-err-at-point))
+
+    (defadvice flymake-goto-prev-error (after display-message activate compile)
+      "Display the error in the mini-buffer rather than having to mouse over it"
+      (show-fly-err-at-point))
diff --git a/doc/index.rst b/doc/index.rst
index 73e24e6..ee0e29f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,15 +1,37 @@
 
-Pylint
-======
+Pylint User Manual
+==================
 
 .. toctree::
    :maxdepth: 2
 
-   manual
-   quickstart
-   tutorial
+   intro
+   run
+   output
+   message-control
    features
-   flymake
-   FAQ
+   extend
+   ide-integration
+   contribute
+
+   tutorial
+   faq
    wiki
+   backlinks
+   installation
+
+
+Content wanted
+--------------
+
+It would be nice to include in the documentation the following information:
+
+- pylint plugins (how to write one, how to install a 3rd party plugin, how to
+  configure Pylint to run it)
+
+- pylint brain project : what it is, how to install it...
+
+Please send your pull requests via bitbucket if you can help with the above.
+
+
 
diff --git a/doc/installation.rst b/doc/installation.rst
new file mode 100644
index 0000000..fac0c24
--- /dev/null
+++ b/doc/installation.rst
@@ -0,0 +1,86 @@
+
+Installation
+------------
+
+Dependencies
+''''''''''''
+Pylint requires the latest `logilab-astng`_ and `logilab-common`_
+packages. It should be compatible with any Python version >= 2.5.
+
+.. _`logilab-astng`: http://www.logilab.org/project/name/astng
+.. _`logilab-common`: http://www.logilab.org/project/name/common
+
+
+Distributions
+'''''''''''''
+The source tarball is available at ftp://download.logilab.org/pub/pylint.
+
+You may apt-get a well-tested debian or ubuntu package by adding one of::
+
+    deb http://download.logilab.org/production unstable/
+    deb http://download.logilab.org/production sid/
+    deb http://download.logilab.org/production squeeze/
+    deb http://download.logilab.org/production lenny/
+
+to your */etc/apt/sources.list* file. Pylint is also available in the
+standard Debian distribution (but add our public debian repository
+anyway if you want to get the latest releases and upgrades earlier)
+
+Pylint is also available in Gentoo, Fedora 4, Ubuntu, FreeBSD, Darwin
+(and maybe others, if you know about more OSes, please drop us a note!).
+
+
+Source distribution installation
+''''''''''''''''''''''''''''''''
+From the source distribution, extract the tarball, go to the extracted
+directory and simply run ::
+
+    python setup.py install
+
+You'll have to install dependencies in a similar way.
+
+Windows users may get valuable information about pylint installation on
+`this page`_.
+
+.. _`this page`: http://thinkhole.org/wp/2006/01/16/installing-pylint-on-windows/
+
+
+Note for Windows users
+''''''''''''''''''''''
+
+On Windows, once you have installed Pylint, the command line usage is ::
+
+  pylint.bat [options] module_or_package
+
+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:
+
+1. change to the appropriate directory before running pylint.bat
+
+2. add the Scripts directory to your path statement in your autoexec.bat
+   file (this file is found in the root directory of your boot-drive)
+
+3. create a 'redirect' batch file in a directory actually on your
+   systems path
+
+To effect (2), simply append the appropriate directory name to the PATH=
+statement in autoexec.bat. Be sure to use the Windows directory
+separator of ';' between entries. Then, once you have rebooted (this is
+necessary so that the new path statement will take effect when
+autoexec.bat is run), you will be able to invoke Pylint with
+pylint.bat on the command line.
+
+(3) is the best solution. Once done, you can call Pylint at the command
+line without the .bat, just as do non-Windows users by typing: ::
+
+  pylint [options] module_or_package
+
+To effect option (3), simply create a plain text file pylint.bat with
+the single line: ::
+
+  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).
diff --git a/doc/intro.rst b/doc/intro.rst
new file mode 100644
index 0000000..f825474
--- /dev/null
+++ b/doc/intro.rst
@@ -0,0 +1,84 @@
+.. -*- coding: utf-8 -*-
+
+==============
+ Introduction
+==============
+
+What is Pylint?
+---------------
+
+Pylint is a tool that checks for errors in Python code, tries to 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 `PEP 008`_ (aka `Guido's style guide`_). For more information about
+code smells, refer to Martin Fowler's `refactoring book`_
+
+Pylint will display a number of messages as it analyzes the code, as well as
+some statistics about the number of warnings and errors found in different
+files. The messages are classified under various categories such as errors and
+warnings (more below). If you run Pylint twice, it will display the statistics
+from the previous run together with the ones from the current run, so that you
+can see if the code has improved or not.
+
+Last but not least, the code is given an overall mark, based on the number an
+severity of the warnings and errors. This has proven to be very motivating for
+some programmers.
+
+Pylint was born in 2003 at Logilab_, that funded Sylvain Thénault to lead its
+development up to now.
+
+.. _pychecker: http://pychecker.sf.net
+.. _`PEP 008`: http://www.python.org/dev/peps/pep-0008/
+.. _`Guido's style guide`: http://www.python.org/doc/essays/styleguide.html
+.. _`refactoring book`: http://www.refactoring.com/
+.. _Logilab: http://www.logilab.fr
+
+What Pylint is not?
+-------------------
+
+What Pylint says is not to be taken as gospel and Pylint isn't smarter than you
+are: it may warn you about things that you have conscientiously done.
+
+Pylint tries hard to report as few false positives as possible for errors, but
+it may be too verbose with warnings. That's for example because it tries to
+detect things that may be dangerous in a context, but are not in others, or
+because it checks for some things that you don't care about. Generally, you
+shouldn't expect Pylint to be totally quiet about your code, so don't
+necessarily be alarmed if it gives you a hell lot of messages for your project!
+
+:Quoting Alexandre Fayolle:
+  My usage pattern for Pylint is to generally run ``pylint -e`` quite often to
+  get stupid errors flagged before launching an application (or before
+  committing). I generally run Pylint with all the bells and whistles
+  activated some time before a release, when I want to cleanup the code.
+  And when I do that I simply ignore tons of the false warnings (and I
+  can do that without being driven mad by this dumb program which is not
+  smart enough to understand the dynamicity of Python because I only run
+  it once or twice a week in this mode)
+
+:Quoting Marteen Ter Huurne:
+  In our project we just accepted that we have to make some modifications in our
+  code to please Pylint:
+
+  - stick to more naming conventions (unused variables ending in underscores,
+    mix-in class names ending in "Mixin")
+
+  - making all abstract methods explicit (rather than just not defining them in
+    the superclass)
+
+  - add ``# pylint: disable=X0123`` comments:
+
+    - for messages which are useful in general, but not in a specific case
+
+    - for Pylint bugs
+
+    - for Pylint limitations (for instance Twisted's modules create a lot of
+      definitions dynamically so Pylint does not know about them)
+
+  The effort is worth it, since Pylint helps us a lot in keeping the code clean
+  and finding errors early. Although most errors found by Pylint would also be
+  found by the regression tests, by fixing them before committing, we save time.
+  And our regression tests do not cover all code either, just the most complex
+  parts.
+
diff --git a/doc/makefile b/doc/makefile
deleted file mode 100644
index df739fb..0000000
--- a/doc/makefile
+++ /dev/null
@@ -1,46 +0,0 @@
-MKHTML=mkdoc
-MKHTML_OPT=--param toc.section.depth=1 --target html --stylesheet standard 
-
-SRC=.
-
-
-all: manual.html quickstart.html features.html FAQ.html beginner_pylint_tutorial.html examples man
-
-FAQ.html: ${SRC}/FAQ.txt
-	${MKHTML} ${MKHTML_OPT} ${SRC}/FAQ.txt
-
-quickstart.html: ${SRC}/quickstart.txt
-	${MKHTML} ${MKHTML_OPT} ${SRC}/quickstart.txt
-
-manual.html: ${SRC}/manual.txt ${SRC}/FAQ.txt
-	${MKHTML} ${MKHTML_OPT} ${SRC}/manual.txt
-
-beginner_pylint_tutorial.html: ${SRC}/beginner_pylint_tutorial.txt
-	${MKHTML} ${MKHTML_OPT} ${SRC}/beginner_pylint_tutorial.txt
-
-features.html:
-	chmod u+w ${SRC}/features.txt
-	echo ".. class:: article" > ${SRC}/features.txt
-	echo "" >> ${SRC}/features.txt
-	echo "Pylint features" > ${SRC}/features.txt
-	echo "===============" >> ${SRC}/features.txt
-	echo "" >> ${SRC}/features.txt
-	echo ".. generated by pylint" >> ${SRC}/features.txt
-	echo "" >> ${SRC}/features.txt
-	echo ".. contents::" >> ${SRC}/features.txt
-	echo "" >> ${SRC}/features.txt
-	pylint --full-documentation >> ${SRC}/features.txt
-	${MKHTML} ${MKHTML_OPT} ${SRC}/features.txt
-
-examples:
-	chmod u+w ../examples/pylintrc
-	pylint --generate-rcfile > ../examples/pylintrc
-
-man:
-	chmod u+w ../man/pylint.1
-	pylint --generate-man > ../man/pylint.1
-
-clean:
-	rm -f *.html
-
-.PHONY: features.html
diff --git a/doc/message-control.rst b/doc/message-control.rst
new file mode 100644
index 0000000..d93b452
--- /dev/null
+++ b/doc/message-control.rst
@@ -0,0 +1,97 @@
+
+Messages control
+----------------
+
+An example available from the examples directory:
+
+.. sourcecode:: python
+
+    """pylint option block-disable"""
+
+    __revision__ = None
+
+    class Foo(object):
+        """block-disable test"""
+
+        def __init__(self):
+            pass
+
+        def meth1(self, arg):
+            """this issues a message"""
+            print self
+
+        def meth2(self, arg):
+            """and this one not"""
+            # pylint: disable=W0613
+            print self\
+                  + "foo"
+
+        def meth3(self):
+            """test one line disabling"""
+            # no error
+            print self.bla # pylint: disable=E1101
+            # error
+            print self.blop
+
+        def meth4(self):
+            """test re-enabling"""
+            # pylint: disable=E1101
+            # no error
+            print self.bla
+            print self.blop
+            # pylint: enable=E1101
+            # error
+            print self.blip
+
+        def meth5(self):
+            """test IF sub-block re-enabling"""
+            # pylint: disable=E1101
+            # no error
+            print self.bla
+            if self.blop:
+                # pylint: enable=E1101
+                # error
+                print self.blip
+            else:
+                # no error
+                print self.blip
+            # no error
+            print self.blip
+
+        def meth6(self):
+            """test TRY/EXCEPT sub-block re-enabling"""
+            # pylint: disable=E1101
+            # no error
+            print self.bla
+            try:
+                 pylint: enable=E1101
+                # error
+                print self.blip
+            except UndefinedName: # pylint: disable=E0602
+                # no error
+                print self.blip
+            # no error
+            print self.blip
+
+        def meth7(self):
+            """test one line block opening disabling"""
+            if self.blop: # pylint: disable=E1101
+                # error
+                print self.blip
+            else:
+                # error
+                print self.blip
+            # error
+            print self.blip
+
+
+        def meth8(self):
+            """test late disabling"""
+            # error
+            print self.blip
+            # pylint: disable=E1101
+            # no error
+            print self.bla
+            print self.blop
+
+
diff --git a/doc/output.rst b/doc/output.rst
new file mode 100644
index 0000000..ffb9977
--- /dev/null
+++ b/doc/output.rst
@@ -0,0 +1,72 @@
+
+Pylint output
+-------------
+
+The default format for the output is raw text. You can change this by passing
+pylint the ``--output-format=<value>`` option. Possible values are: parseable,
+colorized, msvs (visual studio) and html.
+
+There are several sections in pylint's output.
+
+Source code analysis section
+''''''''''''''''''''''''''''
+
+For each python module, Pylint will first display a few '*' characters followed
+by the name of the module. Then, a number of messages with the following format:
+::
+
+  MESSAGE_TYPE: LINE_NUM:[OBJECT:] MESSAGE
+
+You can get another output format, useful since it's recognized by
+most editors or other development tools using the ``--output-format=parseable``
+option.
+
+The message type can be:
+
+  * [R]efactor for a "good practice" metric violation
+  * [C]onvention for coding standard violation
+  * [W]arning for stylistic problems, or minor programming issues
+  * [E]rror for important programming issues (i.e. most probably bug)
+  * [F]atal for errors which prevented further processing
+
+Sometimes the line of code which caused the error is displayed with
+a caret pointing to the error. This may be generalized in future
+versions of Pylint.
+
+Example (extracted from a run of Pylint on itself...):
+
+::
+
+  ************* Module pylint.checkers.format
+  W: 50: Too long line (86/80)
+  W:108: Operator not followed by a space
+       print >>sys.stderr, 'Unable to match %r', line
+              ^
+  W:141: Too long line (81/80)
+  W: 74:searchall: Unreachable code
+  W:171:FormatChecker.process_tokens: Redefining built-in (type)
+  W:150:FormatChecker.process_tokens: Too many local variables (20/15)
+  W:150:FormatChecker.process_tokens: Too many branches (13/12)
+
+
+Reports section
+'''''''''''''''
+
+Following the analysis message, Pylint will display a set of reports,
+each one focusing on a particular aspect of the project, such as number
+of messages by categories, modules dependencies...
+
+For instance, the metrics report displays summaries gathered from the
+current run.
+
+  * the number of processed modules
+  * for each module, the percentage of errors and warnings
+  * the total number of errors and warnings
+  * percentage of classes, functions and modules with docstrings, and
+    a comparison from the previous run
+  * percentage of classes, functions and modules with correct name
+    (according to the coding standard), and a comparison from the
+    previous run
+  * a list of external dependencies found in the code, and where they appear
+
+Also, a global evaluation for the code is computed.
diff --git a/doc/run.rst b/doc/run.rst
new file mode 100644
index 0000000..7360c3e
--- /dev/null
+++ b/doc/run.rst
@@ -0,0 +1,114 @@
+================
+ Running Pylint
+================
+
+Invoking Pylint
+---------------
+
+Pylint is meant to be called from the command line. The usage is ::
+
+   pylint [options] module_or_package
+
+You should give Pylint the name of a python package or module. Pylint
+will ``import`` this package or module, so you should pay attention to
+your ``PYTHONPATH``, since it is a common error to analyze an
+installed version of a module instead of the development version.
+
+It is also possible to analyze python files, with a few
+restrictions. The thing to keep in mind is that Pylint will try to
+convert the file name to a module name, and only be able to process
+the file if it succeeds.  ::
+
+  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.
+
+For more details on this see the Frequently Asked Questions.
+
+You can also start a thin gui around Pylint (require TkInter) by
+typing ::
+
+  pylint-gui
+
+This should open a window where you can enter the name of the package
+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 to ``py_run()`` function in ``lint`` module,
+assuming Pylint options are stored in ``pylint_options`` string, as:
+
+.. sourcecode:: python
+
+  from pylint import epylint as lint
+  lint.py_run(pylint_options)
+
+To silently run Pylint on a ``module_name.py`` module,
+and get its standart output and error:
+
+.. sourcecode:: python
+
+  from pylint import epylint as lint
+  (pylint_stdout, pylint_stderr) = lint.py_run('module_name.py', True)
+
+
+Command line options
+--------------------
+
+First of all, we have two basic (but useful) options.
+
+--version             show program's version number and exit
+-h, --help            show help about the command line options
+
+Pylint is architectured around several checkers. By default all
+checkers are enabled. You can disable a specific checker or some of its
+messages or messages categories by specifying
+``--disable=<id>``. If you want to enable only some checkers or some
+message ids, first use ``--disable=all`` then
+``--enable=<id>`` with <id> being a comma separated list of checker
+names and message identifiers. See the list of available features for a
+description of provided checkers with their functionalities.
+The ``--disable`` and ``--enable`` options can be used with comma separated lists
+mixing checkers, message ids and categories like ``-d C,W,E0611,design``
+
+It is possible to disable all messages with ``--disable=all``. This is
+useful to enable only a few checkers or a few messages by first
+disabling everything, and then re-enabling only what you need.
+
+Each checker has some specific options, which can take either a yes/no
+value, an integer, a python regular expression, or a comma separated
+list of values (which are generally used to override a regular
+expression in special cases). For a full list of options, use ``--help``
+
+Specifying all the options suitable for your setup and coding
+standards can be tedious, so it is possible to use a rc file to
+specify the default values. Pylint looks for ``/etc/pylintrc`` and
+``~/.pylintrc``. The ``--generate-rcfile`` option will generate a
+commented configuration file according to the current configuration on
+standard output and exit. You can put other options before this one to
+use them in the configuration, or start with the default values and
+hand tune the configuration.
+
+Other useful global options include:
+
+--zope                  Initialize Zope products before starting
+--ignore=file           Add <file> (may be a directory) to the black
+                          list. It should be a base name, not a path.
+                          You may set this option multiple times.
+--statistics=y_or_n     Compute statistics on collected data.
+--persistent=y_or_n     Pickle collected data for later comparisons.
+--comment=y_or_n        Add a comment according to your evaluation note.
+--parseable=y_or_n      Use a parseable output format.
+--html=y_or_n           Use HTML as output format instead of text.
+--list-msgs             Generate pylint's messages.
+--full-documentation    Generate pylint's full documentation, in reST format.
+--include_ids=y_or_n    Show numeric ids of messages (like 'C0301')
+--symbols=y_or_n        Show symbolic ids of messsages (like 'line-too-long')
+
+
diff --git a/doc/tutorial.rst b/doc/tutorial.rst
index 0ffdeda..5561c50 100644
--- a/doc/tutorial.rst
+++ b/doc/tutorial.rst
@@ -351,7 +351,7 @@ Here is the updated code:
 
 And here is what happens when we run it with our --disable=W0402 option:
 
-.. sourcecode:: python
+.. sourcecode:: bash
 
   robertk01 Desktop$ pylint --reports=n --include-ids=y --disable=W0402 simplecaeser.py
   No config file found, using default configuration
@@ -396,10 +396,10 @@ example but go ahead and `read up`_ on them if you want.
  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
+ 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.
+That's it for the basic intro. More tutorials will follow.
 
 .. _`read up`: http://docs.python.org/library/re.html