From a3d15fc56a019443d6ae7ac4502c5cefa8959ff8 Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Thu, 19 May 2022 20:04:11 +0200 Subject: [doc] Uniformize the introduction for Readme and doc --- README.rst | 66 ++++++++++++++++++++++++++++++-------------------------------- 1 file changed, 32 insertions(+), 34 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 4da6a750f..d951f7a70 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,5 @@ - -README for Pylint - https://pylint.pycqa.org/ -============================================= +Pylint +====== .. image:: https://github.com/PyCQA/pylint/actions/workflows/tests.yaml/badge.svg?branch=main :target: https://github.com/PyCQA/pylint/actions @@ -8,7 +7,6 @@ README for Pylint - https://pylint.pycqa.org/ .. image:: https://coveralls.io/repos/github/PyCQA/pylint/badge.svg?branch=main :target: https://coveralls.io/github/PyCQA/pylint?branch=main - .. image:: https://img.shields.io/pypi/v/pylint.svg :alt: Pypi Package version :target: https://pypi.python.org/pypi/pylint @@ -40,32 +38,44 @@ README for Pylint - https://pylint.pycqa.org/ .. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-pylint?utm_source=pypi-pylint&utm_medium=referral&utm_campaign=readme +Documentation +============= -====== -Pylint -====== +Please check `the full documentation`_. + +.. _`the full documentation`: https://pylint.pycqa.org/ -**It's not just a linter that annoys you!** +What is pylint ? +================ -Pylint is a Python static code analysis tool which looks for programming errors, -helps enforcing a coding standard, sniffs for code smells and offers simple refactoring -suggestions. +.. Do not modify this without also modifying doc/index.rst -It's highly configurable, having special pragmas to control its errors and warnings -from within your code, as well as from an extensive configuration file. -It is also possible to write your own plugins for adding your own checks or for -extending pylint in one way or another. +Pylint is a `static code analyser`_ for Python 2 or 3. The latest version supports Python +3.7.2 and above. -It's a free software distributed under the GNU General Public Licence unless -otherwise specified. +.. _`static code analyser`: https://en.wikipedia.org/wiki/Static_code_analysis -Development is hosted on GitHub: https://github.com/PyCQA/pylint/ +Pylint analyses your code without actually running it. It checks for errors, enforces a coding +standard, looks for `code smells`_, and can make suggestions about how the code could be refactored. -You can use the code-quality@python.org mailing list to discuss about -Pylint. Subscribe at https://mail.python.org/mailman/listinfo/code-quality/ -or read the archives at https://mail.python.org/pipermail/code-quality/ +.. _`code smells`: https://martinfowler.com/bliki/CodeSmell.html -Pull requests are amazing and most welcome. +Pylint can infer actual values from your code using its internal code representation (astroid). +If your code is ``import logging as argparse``, Pylint will know that ``argparse.error(...)`` +is in fact a logging call and not an argparse call. + +Pylint isn't smarter than you: it may warn you about things that you have +conscientiously done or checks for some things that you don't care about. +During adoption, especially in a legacy project where pylint was never enforced, +it's best to start with the ``--errors-only`` flag, then disable +convention and refactor message with ``--disable=C,R`` and progressively +re-evaluate and re-enable messages as your priorities evolve. + +Pylint ships with three additional tools: + +- :ref:`pyreverse ` (standalone tool that generates package and class diagrams.) +- :ref:`symilar ` (duplicate code finder that is also integrated in pylint) +- :ref:`epylint ` (Emacs and Flymake compatible Pylint) Install ------- @@ -91,18 +101,6 @@ For debian and rpm packages, use your usual tools according to your Linux distri More information about installation and available distribution format can be found here_. -Documentation -------------- - -The documentation lives at https://pylint.pycqa.org/. - -Pylint is shipped with following additional commands: - -* pyreverse: an UML diagram generator -* symilar: an independent similarities checker -* epylint: Emacs and Flymake compatible Pylint - - Testing ------- -- cgit v1.2.1