Rework documentation

Changed the documentation in couple of places, merged sections together,
described testing procedures and added more up-to-date information
in general.

13 files changed, 213 insertions, 217 deletions

diff --git a/doc/backlinks.rst b/doc/backlinks.rst
index 8fc42be20..942cb932d 100644
--- a/doc/backlinks.rst
+++ b/doc/backlinks.rst
@@ -2,26 +2,13 @@
 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
+Python code:
+
+* edX (https://github.com/edx)
+* qutebrowser (https://github.com/The-Compiler/qutebrowser)
+* Odoo (https://github.com/OCA)
+* Landscape.io (https://github.com/landscapeio/)
+* Codacy (https://github.com/Codacy/)
+* SaltStack (https://github.com/saltstack)
 * 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
index 5cd50261e..a16e5a9d1 100644
--- a/doc/contribute.rst
+++ b/doc/contribute.rst
@@ -8,10 +8,10 @@ Bug reports, feedback
 ---------------------
 
 You think you have found a bug in Pylint? Well, this may be the case
-since Pylint is under development.
+since Pylint is under heavy development.
 
 Please take the time to check if it is already in the issue tracker at
-https://bitbucket.org/logilab/pylint
+https://github.com/PyCQA/pylint
 
 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.
@@ -29,11 +29,6 @@ astroid.
 Mailing lists
 -------------
 
-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.
-
 You can subscribe to this mailing list at
 http://mail.python.org/mailman/listinfo/code-quality
 
@@ -43,10 +38,11 @@ http://mail.python.org/pipermail/code-quality/
 Archives before April 2013 are available at
 http://lists.logilab.org/pipermail/python-projects/
 
-Forge
------
 
-Pylint is developed using the mercurial_ distributed version control system.
+Repository
+----------
+
+Pylint is developed using the git_ distributed version control system.
 
 You can clone Pylint and its dependencies from ::
 
@@ -54,22 +50,26 @@ You can clone Pylint and its dependencies from ::
   hg clone https://bitbucket.org/logilab/astroid
   hg clone http://hg.logilab.org/logilab/common
 
-.. _mercurial: http://www.selenic.com/mercurial/
+.. _git: https://git-scm.com/
 
 Got a change for Pylint?  Below are a few steps you should take to make sure
 your patch gets accepted.
 
 - Test your code
 
-    - Pylint keeps a set of unit tests in the /test directory. The
-      `test_func.py` module uses external files to have some kind of easy
-      functional testing. To get your patch accepted you must write (or change)
-      a test input file in the `test/input` directory and message file in the
-      `test/messages` directory. Then run `python test_func.py` to ensure that
-      your test is green.
+    - Pylint is very well tested, with a high good code coverage.
+      It has two types of tests, usual unittests and functional tests.
+
+      The usual unittests can be found under `/test` directory and they can
+      be used for testing almost anything Pylint related. But for the ease
+      of testing Pylint's messages, we also have the concept of functional tests.             
 
     - You should also run all the tests to ensure that your change isn't
-      breaking one.
+      breaking one. You can run the tests using the tox_ package, as in::
+
+          python -m tox
+          python -m tox -epy27 # for Python 2.7 suite only
+          python -m tox -epylint # for running Pylint over Pylint's codebase
 
 - Add a short entry to the ChangeLog describing the change, except for internal
   implementation only changes
@@ -79,51 +79,40 @@ your patch gets accepted.
 - Relate your change to an issue in the tracker if such an issue exists (see
   `this page`_ of Bitbucket documentation for more information on this)
 
-- Send a pull request from Bitbucket (more on this here_)
-
-.. _`this page`: https://confluence.atlassian.com/display/BITBUCKET/Resolve+issues+automatically+when+users+push+code
-.. _here: https://confluence.atlassian.com/display/BITBUCKET/Work+with+pull+requests
-
-
-Unit test setup
----------------
+- Document your change, if it is a non-trivial one.
 
-If you have tox installed, running ``tox`` command should be
-enough to get you started. Otherwise, you can follow this recipe
-for running the tests for pylint::
+- Send a pull request from GitHub (more on this here_)
 
-   python setup.py develop # or ``pip install -e .``
-   cd pylint/test
-   python -m unittest discover -p "*test*"
 
+Functional tests
+----------------
 
-Adding new functional tests
-----------------------------
+These are residing under '/test/functional' and they are formed of multiple
+components. First, each Python file is considered to be a test case and it
+should be accompanied by a .txt file, having the same name, with the messages
+that are supposed to be emitted by the given test file.
 
-Pylint comes with an easy way to write functional tests for new checks:
+In the Python file, each line for which Pylint is supposed to emit a message
+has to be annotated with a comment in the form ``# [message_symbol]``, as in::
 
-* put a Python file in the `test/input` directory, whose name starts with
-  `func_` and should also contains the symbolic name of the tested check
+    a, b, c = 1 # [unbalanced-tuple-unpacking]
 
-* add the expected message file in the `test/messages` directory, using the
-  same name but a `.txt` extension instead of `.py`
+If multiple messages are expected on the same line, then this syntax can be used::
 
-The message file should use the default text output format (without reports) and lines should be
-sorted. E.g on Unix system, you may generate it using::
+    a, b, c = 1.test # [unbalanced-tuple-unpacking, no-member]
 
-  pylint -rn input/func_mycheck.py | sort > pylint messages/func_mycheck.txt
+The syntax of the .txt file has to be this::
 
-Also, here are a few naming convention which are used:
+    symbol:line_number:function_or_class:Expected message
 
-* Python files starting with 'func_noerror' don't have any message file
-  associated as they are expected to provide no output at all
+For example, this is a valid message line::
 
-* You may provide different input files (and associated output) depending on the
-  Python interpreter version:
+    abstract-class-instantiated:79:main:Abstract class 'BadClass' with abstract methods instantiated
 
-  * tests whose name ends with `_py<xy>.py` are used for Python >= x.y
-  * tests whose name ends with `_py<_xy>.py` are used for Python < x.y
+If the Python file is expected to not emit any errors, then the .txt file has to be empty.
+If you need special control over Pylint's flag, you can also create a .rc file, which
+can have sections of Pylint's configuration.
 
-* Similarly you may provide different message files for a single input, message
-  file whose name ends with '_py<xy>.txt' will be used for Python >= x.y, using
-  the nearest version possible
+.. _`this page`: https://help.github.com/articles/closing-issues-via-commit-messages/
+.. _here: https://help.github.com/articles/using-pull-requests/
+.. _tox: http://tox.readthedocs.io/en/latest/
diff --git a/doc/extend.rst b/doc/extend.rst
deleted file mode 100644
index b7678527f..000000000
--- a/doc/extend.rst
+++ /dev/null
@@ -1,36 +0,0 @@
-
-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 `ast 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>` 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:
-
-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 ``leave_<>`` 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 code-quality mailing list.
-
-.. _`ast package`: http://docs.python.org/2/library/ast
diff --git a/doc/faq.rst b/doc/faq.rst
index 3002bdd79..5fbd61bc5 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -33,11 +33,15 @@ Pylint doesn't?`_).
 ---------------------
 
 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.
+Sylvain Thénault, while he worked at Logilab_ where the project was born.
+The project is now under the umbrella of the PyCQA_ organization, where it is
+maintained by Claudiu Popa and contributors.
+
+For a full list of contributors, see the "Contributors" file under's Pylint's
+repository
 
 .. _Logilab: http://www.logilab.fr/
+.. _PyCQA: https://github.com/PyCQA/
 
 1.4 Who uses Pylint?
 --------------------
@@ -66,10 +70,11 @@ Pylint from the repository, simply invoke ::
 2.3 What are Pylint's dependencies?
 -----------------------------------
 
-Pylint requires the latest `astroid`_. It should be
-compatible with any Python version greater than 2.7.0.
+Pylint depends on astroid_ and a couple of other packages.
+It should be compatible with any Python version greater than 2.7.0 and
+it is also working on PyPy.
 
-.. _`astroid`: https://bitbucket.org/logilab/astroid
+.. _`astroid`: https://github.com/PyCQA/astroid
 
 2.4 What versions of Python is Pylint supporting?
 --------------------------------------------------
@@ -79,9 +84,6 @@ Using this strategy really helps in maintaining a code base compatible
 with both versions and from this benefits not only the maintainers,
 but the end users as well, because it's easier to add and test
 new features.
-If support for Python 2.6 is absolutely required, then the version
-from pylint-1.3 branch can be used. It will receive backports of
-bug fixes for a while.
 
 
 3. Running Pylint
@@ -99,8 +101,8 @@ the file's path using the python path. Some examples :
 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.
+package (i.e. has an __init__.py file), an implicit namespace package
+or if "directory" is in the python path.
 
 "pylint /whatever/directory/mymodule.py" will work if either:
 
@@ -111,6 +113,8 @@ python path.
 	- "directory" is a python package and "/whatever" is in the python
           path
 
+        - "directory" is an implicit namespace package and is in the python path.
+
 	- "directory" is a python package and your cwd is "/whatever" and so
           on...
 
diff --git a/doc/generated_features.rst b/doc/generated_features.rst
new file mode 100644
index 000000000..8ab6b9c88
--- /dev/null
+++ b/doc/generated_features.rst
@@ -0,0 +1,5 @@
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   features
\ No newline at end of file
diff --git a/doc/ide-integration.rst b/doc/ide-integration.rst
index ed0c1be0f..cf1188205 100644
--- a/doc/ide-integration.rst
+++ b/doc/ide-integration.rst
@@ -1,7 +1,7 @@
 
-============================
+###########################
  Editor and IDE integration
-============================
+###########################
 
 To use Pylint with:
 
diff --git a/doc/index.rst b/doc/index.rst
index 452a48b98..0d677c47b 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -2,37 +2,26 @@
 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
+   :maxdepth: 1
+   :titlesonly:
 
    intro
+   contribute
    whatsnew/index.rst
+   tutorial
+
+   installation
    run
    output
    message-control
-   features
+   generated_features
    extensions
    options
-   extend
    ide-integration
    plugins
-   contribute
 
-   tutorial
    faq
    backlinks
-   installation
-
-
-
-Content wanted
---------------
-
-It would be nice to include in the documentation the following information:
 
-- 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
index ec21ccf01..3987f1d34 100644
--- a/doc/installation.rst
+++ b/doc/installation.rst
@@ -1,40 +1,15 @@
 Installation
 ------------
 
-Dependencies
-''''''''''''
-
-Pylint requires the latest `astroid`_ package.
-It should be compatible with any Python version >= 2.7.
-
-.. _`astroid`: https://bitbucket.org/logilab/astroid
-
-
-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 these
-lines::
-
-    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!).
 
 Python packages
 '''''''''''''''
 
-Pylint should be easily installable using setuptools and the Python Package
-Index. Try easy_install or pip, depending on your preference.
+Pylint should be easily installable using pip.
+
+.. code-block:: sh
+
+   python -m pip install pip
 
 
 Source distribution installation
@@ -45,12 +20,9 @@ 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`_.
+Or you can install it in editable mode, using ::
 
-.. _`this page`: http://thinkhole.org/wp/2006/01/16/installing-pylint-on-windows/
+    python setup.py develop
 
 
 Note for Windows users
@@ -92,3 +64,9 @@ the single line: ::
 
 (where PythonDirectory is replaced by the actual Python installation
 directory on your system -- e.g. C:\Python24\Scripts\pylint.bat).
+
+Alternatively, you can run pylint using the ``-m`` flag, as in:
+
+.. code-block:: sh
+
+    python -m pylint module_or_package
diff --git a/doc/intro.rst b/doc/intro.rst
index 2b8b17c00..1e86b374f 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -8,31 +8,34 @@ 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.
+coding standard and looks for code smells. It can also look for certain type
+errors, it can recommend suggestions about how particular blocks
+can be refactored and can offer you details about the code's complexity.
+
+Other similar projects would include the now defunct pychecker_, pyflakes_,
+flake8_ and mypy_. The default coding style used by Pylint is close to `PEP 008`_.
+
+Pylint will display a number of messages as it analyzes the code and it can
+also be used for displaying 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.
+
+Last but not least, the code is given an overall mark, based on the number and
+severity of the warnings and errors.
 
 Pylint was born in 2003 at Logilab_, that funded Sylvain Thénault to lead its
-development up to now.
+development. Since 2015, the project went under the PyCQA_ umbrella, where it
+is currently maintained and developed by a couple of contributors.
 
 .. _pychecker: http://pychecker.sf.net
+.. _pyflakes: https://github.com/pyflakes/pyflakes
+.. _flake8: https://gitlab.com/pycqa/flake8/
+.. _mypy: https://github.com/JukkaL/mypy
 .. _`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
+.. _PyCQA: https://github.com/PyCQA
 
 What Pylint is not?
 -------------------
@@ -47,6 +50,17 @@ 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!
 
+The best way to tackle pylint's verboseness is to:
+
+  * enable or disable the messages or message categories that you want to be
+    activated or not for when pylint is analyzing your code.
+    This can be done easily through a command line flag. For instance, disabling
+    all convention messages is simple as a ``--disable=C`` option added to pylint
+    command.
+
+  * create a custom configuration file, tailored to your needs. You can generate
+    one using pylint's command ``--generate-rcfile``.
+
 :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
diff --git a/doc/make.bat b/doc/make.bat
index 94826798c..10ab0da00 100644
--- a/doc/make.bat
+++ b/doc/make.bat
@@ -44,7 +44,15 @@ if "%1" == "clean" (
 	goto end
 )
 
+
 if "%1" == "html" (
+	rm -f features.rst
+	echo Pylint features > features.rst
+	echo =============== >> features.rst
+	echo  >> features.rst
+	echo .. generated by pylint --full-documentation >> features.rst
+	echo  >> features.rst
+	python -m pylint --full-documentation >> features.rst
 	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
 	if errorlevel 1 exit /b 1
 	echo.
diff --git a/doc/output.rst b/doc/output.rst
index 389becd45..a3a9e55e0 100644
--- a/doc/output.rst
+++ b/doc/output.rst
@@ -3,8 +3,8 @@ 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.
+pylint the ``--output-format=<value>`` option. Possible values are: json,
+parseable, colorized, msvs (visual studio) and html.
 
 Moreover you can customize the exact way information are displayed using the
 `--msg-template=<format string>` option. The `format string` uses the
@@ -102,9 +102,11 @@ Example (extracted from a run of Pylint on itself...):
 Reports section
 '''''''''''''''
 
-Following the analysis message, Pylint will display a set of reports,
+Following the analysis message, Pylint can display a set of reports,
 each one focusing on a particular aspect of the project, such as number
-of messages by categories, modules dependencies...
+of messages by categories, modules dependencies. These features can
+be enabled through the ``--report=y`` option, or its shorthand
+version ``-rn``.
 
 For instance, the metrics report displays summaries gathered from the
 current run.
diff --git a/doc/plugins.rst b/doc/plugins.rst
index 052c13f2a..1c60b8f6f 100644
--- a/doc/plugins.rst
+++ b/doc/plugins.rst
@@ -4,6 +4,40 @@
 Plugins

 =======

 

+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 `ast 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>` 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:

+

+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 ``leave_<>`` 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 code-quality mailing list.

+

+.. _`ast package`: http://docs.python.org/2/library/ast

+

+

 Why write a plugin?

 -------------------

 

diff --git a/doc/run.rst b/doc/run.rst
index 42f883136..a9b563113 100644
--- a/doc/run.rst
+++ b/doc/run.rst
@@ -28,8 +28,9 @@ 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.
+will work if ``directory`` is a python package (i.e. has an __init__.py
+file or it is an implicit namespace package) or if "directory" is in the
+python path.
 
 For more details on this see the :ref:`faq`.
 
@@ -68,16 +69,15 @@ 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
+Pylint is architectured around several checkers. you can disable a specific
+checker or some of its messages or messages categories by specifying
+``--disable=<symbol>``. If you want to enable only some checkers or some
+message symbols, first use ``--disable=all`` then
+``--enable=<symbol>`` with <symbol> being a comma separated list of checker
+names and message symbols. 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``
+mixing checkers, message ids and categories like ``-d C,W,no-error,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
@@ -121,13 +121,10 @@ configuration.
 
 Other useful global options include:
 
---ignore=<file[,file]>       Add <file> (may be a directory) to the black
-                             list. It should be a base name, not a path.
-                             Multiple entries can be given, separated by
-                             comma.
---persistent=y_or_n        Pickle collected data for later comparisons.
+--ignore=<file[,file...]>  Add files or directories to the blacklist. They
+                           should be base names, not paths.
 --output-format=<format>   Select output format (text, html, custom).
---msg-template=<template>  Modifiy text output message template.
+--msg-template=<template>  Modify text output message template.
 --list-msgs                Generate pylint's messages.
 --full-documentation       Generate pylint's full documentation, in reST
                              format.
@@ -136,12 +133,10 @@ Parallel execution
 ------------------
 
 It is possible to speed up the execution of Pylint. If the running computer
-has more CPUs than one, then the files to be checked could be spread on all
-processors to Pylint sub-processes.
+has more CPUs than one, then the files for checking could be spread on all
+cores via Pylints's sub-processes.
 This functionality is exposed via ``-j`` command line parameter.
-It takes a number of sub-processes that should be spawned.
-If the provided number is 0 then the number of CPUs will be used.
-The default number of workers is 1.
+If the provided number is 0, then the total number of CPUs will be used.
 
 Example::
 
@@ -155,3 +150,30 @@ There are some limitations in running checks in parallel in current
 implementation. It is not possible to use custom plugins
 (i.e. ``--load-plugins`` option), nor it is not possible to use
 initialization hooks (i.e. ``--init-hook`` option).
+
+This will spawn 4 parallel Pylint subprocesses, each provided module being checked
+by one or another subprocess.
+
+
+Exit codes
+----------
+
+Pylint returns bit-encoded exit codes. If applicable the table lists related
+stderr stream message output.
+
+=========  =========================  ==========================================
+exit code  meaning                    stderr stream message
+=========  =========================  ==========================================
+0          no error
+1          fatal message issued
+2          error message issued
+4          warning message issued
+8          refactor message issued
+16         convention message issued
+32         usage error                - "internal error while receiving results\
+                                        from child linter" "Error occured,
+                                        stopping the linter."
+                                      - "<return of linter.help()>"
+                                      - "Jobs number <#> should be greater \
+                                        than 0"
+=========  =========================  ==========================================