[doc] complete refactoring

1 files changed, 114 insertions, 0 deletions

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')
+
+