From af213f498b2ec2fea079cef508135949b724ceaf Mon Sep 17 00:00:00 2001 From: Claudiu Popa Date: Wed, 12 Nov 2014 22:26:04 +0200 Subject: Cleanup through documentation. --- doc/contribute.rst | 6 +++--- doc/extend.rst | 7 ++++--- doc/faq.rst | 3 ++- doc/output.rst | 2 +- doc/run.rst | 33 ++++++++++++++++++--------------- 5 files changed, 28 insertions(+), 23 deletions(-) (limited to 'doc') diff --git a/doc/contribute.rst b/doc/contribute.rst index 6a45dea..43e5dfb 100644 --- a/doc/contribute.rst +++ b/doc/contribute.rst @@ -47,7 +47,7 @@ http://lists.logilab.org/pipermail/python-projects/ Forge ----- -Pylint is developped using the mercurial_ distributed version control system. +Pylint is developed using the mercurial_ distributed version control system. You can clone Pylint and its dependencies from :: @@ -64,7 +64,7 @@ your patch gets accepted. - 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 - functionnal testing. To get your patch accepted you must write (or change) + 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. @@ -117,7 +117,7 @@ without installing them. You can run all the unit tests like so:: The -S flag keeps distutils from interfering with sys.path. YMMV. -Adding new functionnal tests +Adding new functional tests ---------------------------- Pylint comes with an easy way to write functional tests for new checks: diff --git a/doc/extend.rst b/doc/extend.rst index 476c994..b767852 100644 --- a/doc/extend.rst +++ b/doc/extend.rst @@ -8,7 +8,8 @@ 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 : +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 @@ -25,8 +26,8 @@ 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 +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 diff --git a/doc/faq.rst b/doc/faq.rst index 7e2f3cc..c81bbc3 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -1,5 +1,7 @@ .. -*- coding: utf-8 -*- +.. _faq: + ========================== Frequently Asked Questions ========================== @@ -169,7 +171,6 @@ No, starting from 0.25.3, you can use symbolic names for messages:: # pylint: disable=fixme, line-too-long -You can show these symbols in the output with the `-sy` option. 4.5 I have a callback function where I have no control over received arguments. How do I avoid getting unused argument warnings? ---------------------------------------------------------------------------------------------------------------------------------- diff --git a/doc/output.rst b/doc/output.rst index 3a87547..537bfcb 100644 --- a/doc/output.rst +++ b/doc/output.rst @@ -33,7 +33,7 @@ C category fullname of the message category -For exemple the former (pre 1.0) default format can be obtained with:: +For example, the former (pre 1.0) default format can be obtained with:: pylint --msg-template='{msg_id}:{line:3d},{column}: {obj}: {msg}' diff --git a/doc/run.rst b/doc/run.rst index 9b2b218..418e915 100644 --- a/doc/run.rst +++ b/doc/run.rst @@ -31,9 +31,9 @@ directory is automatically added on top of the python path :: 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. +For more details on this see the :ref:`faq`. -You can also start a thin gui around Pylint (require TkInter) by +You can also start a thin gui around Pylint (require tkinter) by typing :: pylint-gui @@ -43,7 +43,7 @@ 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, +thanks to ``py_run()`` function in ``epylint`` module, assuming Pylint options are stored in ``pylint_options`` string, as: .. sourcecode:: python @@ -57,7 +57,7 @@ and get its standard output and error: .. sourcecode:: python from pylint import epylint as lint - (pylint_stdout, pylint_stderr) = lint.py_run('module_name.py', True) + (pylint_stdout, pylint_stderr) = lint.py_run('module_name.py', return_std=True) Command line options @@ -134,20 +134,23 @@ Other useful global options include: 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. -This functionality is exposed via ``-j`` command line parameter. It takes a number of sub-processes -that should be spawned. If provided number is 0 then the number of CPUs will be taken. -Default number is 1. +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. +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. Example:: pylint -j 4 mymodule1.py mymodule2.py mymodule3.py mymodule4.py -This will spawn 4 parallel Pylint sub-process. Each provided module will be checked in parallel. -Discovered problems by checkers are not displayed immediatelly. They are shown just after completing -checking a module. +This will spawn 4 parallel Pylint sub-process, where each provided module will +be checked in parallel. Discovered problems by checkers are not displayed +immediately. They are shown just after completing checking a module. -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). -It is also not possible to use initialization hook (i.e. ``--init-hook`` option). +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). -- cgit v1.2.1