[doc] continue refactoring

9 files changed, 94 insertions, 181 deletions

diff --git a/README b/README
index 89ce088..582d586 100644
--- a/README
+++ b/README
@@ -1,23 +1,22 @@
-README for Pylint (http://www.pylint.org)
-=========================================
+README for Pylint - http://www.pylint.org/
+==========================================
 
 Pylint is a Python source code analyzer which looks for programming errors,
 helps enforcing a coding standard and sniffs for some code smells (as defined in
 Martin Fowler's Refactoring book).
 
-Pylint has many rules enabled by default, way too much to silent them all on a
+Pylint has many rules enabled by default, way too much to silence them all on a
 minimally sized program. It's highly configurable and handle pragmas to control
 it from within your code. Additionally, it is possible to write plugins to add
 your own checks.
 
 It's a free software distributed under the GNU Public Licence.
 
-Development is hosted on bitbucket: https://bitbucket.org/logilab/pylint/ .
-
-You can use the python-projects@logilab.org mailing list to discuss about
-Pylint. Subscribe at http://lists.logilab.org/mailman/listinfo/python-projects
-or read the archives at http://lists.logilab.org/pipermail/python-projects/
+Development is hosted on bitbucket: https://bitbucket.org/logilab/pylint/
 
+You can use the code-quality@python.org mailing list to discuss about
+Pylint. Subscribe at http://lists.python.org/mailman/listinfo/code-quality
+or read the archives at http://lists.python.org/pipermail/code-quality/
 
 Install
 -------
@@ -25,7 +24,7 @@ Install
 Pylint requires the astng (the later the better) and logilab-common (version >=
 0.53) packages.
 
-*  https://bitbucket.org/logilab/astng
+* https://bitbucket.org/logilab/astng
 * http://www.logilab.org/projects/common
 
 From the source distribution, extract the tarball and run ::
@@ -38,7 +37,6 @@ rpm packages, use your usual tools according to your Linux distribution.
 More information about installation and available distribution format
 may be found in the user manual in the *doc* subdirectory.
 
-
 Documentation
 -------------
 
@@ -51,7 +49,6 @@ Pylint is shipped with following additional commands:
 * epylint: Emacs and Flymake compatible Pylint
 * pylint-gui: a graphical interface
 
-
 Contributors
 ------------
 
diff --git a/doc/Makefile b/doc/Makefile
index c4d1280..8b8b3ec 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -35,6 +35,7 @@ help:
 
 clean:
 	-rm -rf $(BUILDDIR)/*
+	-rm -f features.rst
 
 html: features.rst
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -137,8 +138,6 @@ features.rst:
 	echo "" >> features.rst
 	echo ".. generated by pylint --full-documentation" >> features.rst
 	echo "" >> features.rst
-	echo ".. contents::" >> features.rst
-	echo "" >> features.rst
 	pylint --full-documentation >> features.rst
 
 gen-examples:
diff --git a/doc/contribute.rst b/doc/contribute.rst
index 20dd8e4..346ec15 100644
--- a/doc/contribute.rst
+++ b/doc/contribute.rst
@@ -8,88 +8,71 @@ 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.
+since Pylint is under development.
 
-You can check for already reported bugs, planned features on Pylint's tracker
-web page: https://bitbucket.org/logilab/pylint/issues
+Please take the time to check if it is already in the issue tracker at
+https://bitbucket.org/logilab/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
+If you can not find it in the tracker, create a new issue there or discuss your
+problem on the code-quality@python.org mailing list.
+
+The code-quality mailing list is also a nice place to provide feedback about
+Pylint, since it is shared with other tools that aim at improving the quality of
+python code.
+
+Note that if you don't find something you have expected in Pylint's
+issue tracker, it may be because it is an issue with one of its dependencies, namely
 astng and common:
 
-* https://bitbucket.org/logilab/astng/issues
+* https://bitbucket.org/logilab/astng
 * http://www.logilab.org/project/logilab-common
 
-.. _`tracker page`: https://bitbucket.org/logilab/pylint/issues
-
 Mailing lists
 -------------
 
-Use the python-projects@logilab.org mailing list for anything related
+Use the code-quality@python.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.
+be more likely answered by someone subscribed to the list.
 
 You can subscribe to this mailing list at
-http://lists.logilab.org/mailman/listinfo/python-projects
+http://lists.python.org/mailman/listinfo/code-quality
 
 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:
+http://lists.python.org/pipermail/code-quality/
 
-* (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.
+Archives before April 2013 are available at
+http://lists.logilab.org/pipermail/python-projects/
 
-Development
------------
+Forge
+-----
 
-Pylint is developped using the mercurial_ version control system. This is a very
-cool distributed VCS and its usage is very similar to other ones such as cvs or
-subversion (though the distributed feature introduced some different usage
-patterns). See mercurial_ home page for installation on your computer and basic
-usage. Note that it's very easy to send us patches using `hg email` command ;).
+Pylint is developped using the mercurial_ distributed version control system.
 
-You can get the in-development Pylint source code from its bitbucket repository: ::
+You can clone Pylint and its dependencies from ::
 
   hg clone https://bitbucket.org/logilab/pylint
-
-The same is true for Pylint dependencies (if you use Pylint code from the
-repository, you should usually use code from the repository as well for astng
-and logilab-common): ::
-
   hg clone https://bitbucket.org/logilab/astng
   hg clone http://hg.logilab.org/logilab/common
 
 .. _mercurial: http://www.selenic.com/mercurial/
 
-Got a patch for Pylint?  There a few steps you must take to make sure your
+Got a change for Pylint?  There a few steps you must take to make sure your
 patch gets accepted.
 
-* Test your code
+- Test your code
 
-    * Pylint keeps a set of unit tests in the /test directory. To get your
+    - 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
+    - In the test folder of Pylint run ``./fulltest.sh <python versions>``, make sure
       all tests pass before submitting a patch
 
-* Add an entry to the ChangeLog describing the change
+- Add an short entry to the ChangeLog describing the change
 
-* Take care of the commit message
+- Write a comprehensive commit message
 
-* Relate your change to a tracker issue
+- Relate your change to an issue in the tracker
 
-If you don't want to bother with mercurial, you can still create a diff and
-post it to the mailing list or as attachment to a tracker issue.
+- Send a pull request from bitbucket
diff --git a/doc/extend.rst b/doc/extend.rst
index d8a3700..476c994 100644
--- a/doc/extend.rst
+++ b/doc/extend.rst
@@ -13,13 +13,12 @@ First, there are two kinds of checkers :
 * 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 `ast package`_. The extension
+standard Python distribution in the `ast package`_. The extension
 adds additional information and methods on the tree nodes to ease
-navigation and code introspection, as well as compatibility across various
-Python version.
+navigation and code introspection.
 
 An AST checker is a visitor, and should implement
-`visit_<lowered class name>` and/or `leave_<lowered class name>`
+`visit_<lowered class name>` or `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 `ast package`_ documentation.
 Checkers are ordered by priority. For each module, Pylint's engine:
@@ -31,6 +30,6 @@ Checkers are ordered by priority. For each module, Pylint's engine:
 
 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.
+ask for any information on the code-quality mailing list.
 
-.. _`ast package`: http://docs.python.org/2/library/ast.html
+.. _`ast package`: http://docs.python.org/2/library/ast
diff --git a/doc/faq.rst b/doc/faq.rst
index 5e0afbc..15de8c5 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -25,6 +25,8 @@ 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?`_).
 
+.. _Pychecker: http://pychecker.sf.net
+
 1.3 Who wrote Pylint?
 ---------------------
 
@@ -35,19 +37,24 @@ file.
 
 .. _Logilab: http://www.logilab.fr/
 
+1.4 Who uses Pylint?
+--------------------
+
+Everybody knows someone who uses Pylint.
+
 2. Installation
 ===============
 
 2.1 How do I install Pylint?
 ----------------------------
 
-Everything should be explained on http://docs.pylint.org/installation.html
+Everything should be explained on http://docs.pylint.org/installation
 
 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
+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
@@ -67,8 +74,8 @@ compatible with any Python version greater than 2.5.0.
 3. Running Pylint
 =================
 
-3.1 Can I give pylint a file as argument instead of a module?
--------------------------------------------------------------
+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,
@@ -121,8 +128,7 @@ For example::
 3.4 I'd rather not run Pylint from the command line. Can I integrate it with my editor?
 ---------------------------------------------------------------------------------------
 
-Much probably. Read http://docs.pylint.org/ide-integration.html
-
+Much probably. Read http://docs.pylint.org/ide-integration
 
 4. Message Control
 ==================
@@ -130,21 +136,20 @@ Much probably. Read http://docs.pylint.org/ide-integration.html
 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
+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 Is there a way to disable or to enable a message for a particular module only?
-----------------------------------------------------------------------------------
+4.2 Is there a way to disable a message for a particular module only?
+---------------------------------------------------------------------
 
-Yes, you can disable or enable (otherwise globally disabled) messages at the
+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.3 How can I tell Pylint to never check a given module?
 --------------------------------------------------------
 
@@ -166,8 +171,7 @@ No, starting from 0.25.3, you can use symbolic names for messages::
 
 You can show these symbols in the output with the `-sy` option.
 
-
-4.3 I have a callback function where I have no control over received arguments. How do I avoid getting unused argument warnings?
+4.5 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
@@ -175,7 +179,7 @@ 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.5 What is the format of the configuration file?
+4.6 What is the format of the configuration file?
 ---------------------------------------------------
 
 Pylint uses ConfigParser from the standard library to parse the configuration file.
@@ -185,8 +189,7 @@ It means that if you need to disable a lot of messages, you can use tricks like:
      E0202, # I have a good reason, trust me
      C0302  # that's it
 
-
-4.2 Why do I get a lot of spurious "unused variables messages" when using psyobj from psyco_?
+4.7 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()
@@ -210,8 +213,6 @@ objects (i.e. it no longer imports analysed modules)
 
 .. _psyco: http://psyco.sf.net
 
-
-
 5. Classes and Inheritance
 ==========================
 
@@ -270,11 +271,10 @@ traverses an AST representation of the code.
 
 6.3 I think I found a bug in Pylint. What should I do?
 -------------------------------------------------------
-Read http://docs.pylint.org/contribute.html#bug-reports-feedback
+
+Read http://docs.pylint.org/contribute#bug-reports-feedback
 
 6.4 I have a question about Pylint that isn't answered here.
 ------------------------------------------------------------
 
-Read http://docs.pylint.org/contribute.html#mailing-lists
-
-.. _pychecker: http://pychecker.sf.net
+Read http://docs.pylint.org/contribute#mailing-lists
diff --git a/doc/flymake.rst b/doc/flymake.rst
deleted file mode 100644
index 0526b7e..0000000
--- a/doc/flymake.rst
+++ /dev/null
@@ -1,72 +0,0 @@
-====================================
- 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/ide-integration.rst b/doc/ide-integration.rst
index c98fa47..de5116c 100644
--- a/doc/ide-integration.rst
+++ b/doc/ide-integration.rst
@@ -1,18 +1,16 @@
+
 =================
  IDE integration
 =================
 
-Integrating Pylint in my editor/IDE
-===================================
-
-To use Pylint with emacs, see http://www.emacswiki.org/emacs/PythonProgrammingInEmacs#toc8
+To use Pylint with Emacs, see http://www.emacswiki.org/emacs/PythonProgrammingInEmacs#toc8
 
-To use Pylint with vim, see
+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 Eclipse, see http://pydev.org
 
-To use Pylint with komodo_, see
+To use Pylint with Komodo_, see
 http://mateusz.loskot.net/2006/01/15/running-pylint-from-komodo/
 
 To use Pylint with gedit_, see
@@ -23,15 +21,14 @@ 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 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/
+.. _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/
@@ -108,10 +105,9 @@ the following instead of a post-command-hook
       "Display the error in the mini-buffer rather than having to mouse over it"
       (show-fly-err-at-point))
 
-
 Setup the MS Visual Studio .NET 2003 editor to call Pylint
 ==========================================================
 
 .. image:: _static/vs2003_config.jpeg
 
-The output of PyLint is then shown in the "Output" pane of the editor.
+The output of Pylint is then shown in the "Output" pane of the editor.
diff --git a/doc/index.rst b/doc/index.rst
index ee0e29f..790ff93 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -2,6 +2,9 @@
 Pylint User Manual
 ==================
 
+Pylint's home page is at http://www.pylint.org and its forge is at
+https://bitbucket.org/logilab/pylint
+
 .. toctree::
    :maxdepth: 2
 
diff --git a/doc/installation.rst b/doc/installation.rst
index ee9ca6f..976b28b 100644
--- a/doc/installation.rst
+++ b/doc/installation.rst
@@ -1,10 +1,12 @@
+
 Installation
 ------------
 
 Dependencies
 ''''''''''''
+
 Pylint requires the latest `astng`_ and `logilab-common`_
-packages. It should be compatible with any python version >= 2.5.
+packages. It should be compatible with any Python version >= 2.5.
 
 .. _`astng`: https://bitbucket.org/logilab/astng
 .. _`logilab-common`: http://www.logilab.org/project/logilab-common
@@ -12,9 +14,11 @@ packages. It should be compatible with any python version >= 2.5.
 
 Distributions
 '''''''''''''
+
 The source tarball is available at http://download.logilab.org/pub/pylint.
 
-You may apt-get a well-tested Debian or Ubuntu package by adding one of::
+You may apt-get a well-tested Debian or Ubuntu package by adding one of these
+lines::
 
     deb http://download.logilab.org/production unstable/
     deb http://download.logilab.org/production sid/
@@ -22,19 +26,24 @@ You may apt-get a well-tested Debian or Ubuntu package by adding one of::
     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
+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!).
 
+Python packages
+'''''''''''''''
+
+Pylint should be easily installable using setuptools and the Python Package
+Index. Try easy_install or pip, depending on your preference.
+
 
 Source distribution installation
 ''''''''''''''''''''''''''''''''
 
-Pylint should be easily installable using setuptools_'easy_install or
-pip. Though you may still install it from the source distribution: extract the
-tarball: go to the extracted directory and simply run ::
+From the source distribution, extract the tarball, go to the extracted
+directory and simply run ::
 
     python setup.py install
 
@@ -43,7 +52,6 @@ You'll have to install dependencies in a similar way.
 Windows users may get valuable information about Pylint installation on
 `this page`_.
 
-.. _setuptools: http://pypi.python.org/pypi/setuptools
 .. _`this page`: http://thinkhole.org/wp/2006/01/16/installing-pylint-on-windows/
 
 
@@ -74,7 +82,7 @@ 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
+(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