diff --git a/.github/workflows/checks.yaml b/.github/workflows/checks.yaml index b0e9aa6b20..f3551eed26 100644 --- a/.github/workflows/checks.yaml +++ b/.github/workflows/checks.yaml @@ -9,7 +9,7 @@ on: env: # Also change CACHE_VERSION in the other workflows - CACHE_VERSION: 6 + CACHE_VERSION: 7 DEFAULT_PYTHON: 3.8 PRE_COMMIT_CACHE: ~/.cache/pre-commit diff --git a/doc/backlinks.rst b/doc/backlinks.rst deleted file mode 100644 index 9d021ac048..0000000000 --- a/doc/backlinks.rst +++ /dev/null @@ -1,14 +0,0 @@ - -Some projects using Pylint --------------------------- -The following projects are known to use Pylint to help develop better -Python code: - -* edX (https://github.com/edx) -* qutebrowser (https://github.com/qutebrowser/qutebrowser) -* Odoo (https://github.com/OCA) -* Landscape.io (https://github.com/landscapeio/) -* Codacy (https://github.com/Codacy/) -* SaltStack (https://github.com/saltstack) -* CodeFactor (https://github.com/codefactor-io) -* many more... diff --git a/doc/conf.py b/doc/conf.py index b75ea2e0df..fbd73c6649 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -2,16 +2,7 @@ # For details: https://github.com/PyCQA/pylint/blob/main/LICENSE # Copyright (c) https://github.com/PyCQA/pylint/blob/main/CONTRIBUTORS.txt -# Pylint documentation build configuration file, created by -# sphinx-quickstart on Thu Apr 4 20:31:25 2013. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. +from __future__ import annotations import os import sys @@ -24,6 +15,18 @@ # The short X.Y version. from pylint import __version__ +# Pylint documentation build configuration file, created by +# sphinx-quickstart on Thu Apr 4 20:31:25 2013. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -43,8 +46,16 @@ "pylint_options", "sphinx.ext.autosectionlabel", "sphinx.ext.intersphinx", + "sphinx_reredirects", ] +# https://documatt.gitlab.io/sphinx-reredirects/usage.html +redirects: dict[str, str] = { + # "": "" + "intro": "index.html", + "support": "contact.html", +} + # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] diff --git a/doc/contact.rst b/doc/contact.rst new file mode 100644 index 0000000000..c6d0e841ec --- /dev/null +++ b/doc/contact.rst @@ -0,0 +1,58 @@ +Contact +======= + +Bug reports, feedback +--------------------- +.. _bug reports, feedback: + +You think you have found a bug in Pylint? Well, this may be the case +since Pylint and Python are under heavy development! + +Please take the time to check if it is already in the issue tracker at +https://github.com/PyCQA/pylint + +Note that the issue might also be reported in one of Pylint's major dependencies, +astroid: + +* https://github.com/PyCQA/astroid + +Discord server +-------------- + +You can discuss your problem using the discord server: + +https://discord.com/invite/Egy6P8AMB5 + +Mailing lists +------------- + +.. _Mailing lists: + +The code-quality mailing list is shared with other tools that aim +at improving the quality of python code. + +You can subscribe to this mailing list at +https://mail.python.org/mailman3/lists/code-quality.python.org/ + +Archives are available at +https://mail.python.org/pipermail/code-quality/ + +Archives before April 2013 are available at +https://lists.logilab.org/pipermail/python-projects/ + +Support +------- + +.. image:: media/Tidelift_Logos_RGB_Tidelift_Shorthand_On-White.png + :height: 150 + :alt: Tidelift + :align: left + :class: tideliftlogo + +Professional support for pylint is available as part of the `Tidelift +Subscription`_. Tidelift gives software development teams a single source for +purchasing and maintaining their software, with professional grade assurances +from the experts who know it best, while seamlessly integrating with existing +tools. + +.. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-pylint?utm_source=pypi-pylint&utm_medium=referral&utm_campaign=readme diff --git a/doc/development_guide/contribute.rst b/doc/development_guide/contribute.rst index bf8127de53..116dbebcef 100644 --- a/doc/development_guide/contribute.rst +++ b/doc/development_guide/contribute.rst @@ -4,51 +4,6 @@ Contributing ============== -.. _bug reports, feedback: - -Bug reports, feedback ---------------------- - -You think you have found a bug in Pylint? Well, this may be the case -since Pylint is under heavy development! - -Please take the time to check if it is already in the issue tracker at -https://github.com/PyCQA/pylint - -If you cannot find it in the tracker, create a new issue there or discuss your -problem on the code-quality@python.org mailing list or using the discord -server https://discord.com/invite/Egy6P8AMB5. - -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 -astroid: - -* https://github.com/PyCQA/astroid - -.. _Mailing lists: - -Discord server --------------- - -https://discord.com/invite/Egy6P8AMB5 - -Mailing lists -------------- - -You can subscribe to this mailing list at -https://mail.python.org/mailman3/lists/code-quality.python.org/ - -Archives are available at -https://mail.python.org/pipermail/code-quality/ - -Archives before April 2013 are available at -https://lists.logilab.org/pipermail/python-projects/ - - .. _repository: Repository diff --git a/doc/faq.rst b/doc/faq.rst index 21398c1754..fbdccd4c30 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -6,29 +6,13 @@ Frequently Asked Questions ========================== -1. About Pylint -=============== - -1.1 What is Pylint? --------------------- - -Pylint is a `static code checker`_, meaning it can analyse your code without -actually running it. Pylint checks for errors, tries to enforce a coding -standard, and tries to enforce a coding style. - -.. _`static code checker`: https://en.wikipedia.org/wiki/Static_code_analysis - - -2. Installation -=============== - -2.1 How do I install Pylint? ----------------------------- +How do I install Pylint? +------------------------ Everything should be explained on :ref:`installation`. -2.2 What kind of versioning system does Pylint use? ---------------------------------------------------- +What kind of versioning system does Pylint use? +----------------------------------------------- Pylint uses git. To get the latest version of Pylint from the repository, simply invoke :: @@ -36,20 +20,6 @@ Pylint uses git. To get the latest version of Pylint from the repository, simply .. _git: https://git-scm.com/ -2.3 What are Pylint's dependencies? ------------------------------------ - -Pylint depends on astroid_ and a couple of other packages. -See the following section for details on what versions of Python are -supported. - -.. _`astroid`: https://github.com/PyCQA/astroid - -2.4 What versions of Python is Pylint supporting? -------------------------------------------------- - -The supported running environment since Pylint 2.14.0 is Python 3.7.2+. - 3. Running Pylint ================= @@ -303,13 +273,3 @@ Pylint, you can set ``evaluation`` to the above expression to get the new behavior. Likewise, since negative values are still technically supported, ``evaluation`` can be set to a version of the above expression that does not enforce a floor of zero. - -6.2 I think I found a bug in Pylint. What should I do? -------------------------------------------------------- - -Read :ref:`Bug reports, feedback` - -6.3 I have a question about Pylint that isn't answered here. ------------------------------------------------------------- - -Read :ref:`Mailing lists` diff --git a/doc/index.rst b/doc/index.rst index ff2bfd6014..0a77c74634 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,28 +1,53 @@ +Pylint documentation +==================== -Pylint User Manual -================== +Pylint is a `static code analyser`_ for Python 2 or 3. The latest version supports Python +3.7.2 and above. -Pylint is a tool that checks for errors in Python code, tries to enforce a -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. +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. +Projects that you might want to use alongside pylint include flake8_ (faster and simpler checks +with very few false positives), mypy_, pyright_ or pyre_ (typing checks), bandit_ (security +oriented checks), black_ and isort_ (auto-formatting), autoflake_ (automated removal of +unused import or variable), pyupgrade_ (automated upgrade to newer python syntax) and +pydocstringformatter_ (automated pep257). + +.. _flake8: https://gitlab.com/pycqa/flake8/ +.. _bandit: https://github.com/PyCQA/bandit +.. _mypy: https://github.com/python/mypy +.. _pyright: https://github.com/microsoft/pyright +.. _pyre: https://github.com/facebook/pyre-check +.. _black: https://github.com/psf/black +.. _autoflake: https://github.com/myint/autoflake +.. _pyupgrade: https://github.com/asottile/pyupgrade +.. _pydocstringformatter: https://github.com/DanielNoord/pydocstringformatter +.. _isort: https://pycqa.github.io/isort/ +.. _`static code analyser`: https://en.wikipedia.org/wiki/Static_code_analysis +.. _`code smells`: https://martinfowler.com/bliki/CodeSmell.html + +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. .. toctree:: - :maxdepth: 2 :titlesonly: + :hidden: - intro tutorial - user_guide/index.rst how_tos/index.rst messages/index.rst technical_reference/index.rst development_guide/index.rst additional_commands/index.rst - faq - backlinks - support + contact whatsnew/index.rst diff --git a/doc/intro.rst b/doc/intro.rst deleted file mode 100644 index f1c58fcaf3..0000000000 --- a/doc/intro.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. -*- coding: utf-8 -*- - -============== - Introduction -============== - -What is Pylint? ---------------- - -Pylint is a tool that checks for errors in Python code, tries to enforce a -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 pychecker_ (now defunct), pyflakes_, -flake8_, and mypy_. The default coding style used by Pylint is close to `PEP 8`_. - -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. - -.. _pychecker: https://pypi.org/project/PyChecker/ -.. _pyflakes: https://github.com/PyCQA/pyflakes -.. _flake8: https://gitlab.com/pycqa/flake8/ -.. _mypy: https://github.com/python/mypy -.. _`PEP 8`: https://peps.python.org/pep-0008/ -.. _`Guido's style guide`: https://www.python.org/doc/essays/styleguide/ -.. _`refactoring book`: https://www.refactoring.com/ -.. _`code smells`: https://martinfowler.com/bliki/CodeSmell.html - -What Pylint is not? -------------------- - -What Pylint says is not to be taken as gospel and Pylint isn't smarter than you -are: it may warn you about things that you have conscientiously done. - -Pylint tries hard to report as few false positives as possible for errors, but -it may be too verbose with warnings. That's for example because it tries to -detect things that may be dangerous in a context, but are not in others, or -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. - -* manage the configuration through a configuration file. With the option - ``generate-toml-config`` you can create a piece of ``.toml`` text to put - in your ``pyproject.toml`` file. diff --git a/doc/requirements.txt b/doc/requirements.txt index 7464dd948e..3fb58817a2 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,3 +1,4 @@ Sphinx==4.5.0 +sphinx-reredirects<1 furo==2022.4.7 -e . diff --git a/doc/support.rst b/doc/support.rst deleted file mode 100644 index 33f7403799..0000000000 --- a/doc/support.rst +++ /dev/null @@ -1,17 +0,0 @@ -Support -------- - -.. image:: media/Tidelift_Logos_RGB_Tidelift_Shorthand_On-White.png - :width: 100 - :height: 150 - :alt: Tidelift - :align: left - :class: tideliftlogo - -Professional support for pylint is available as part of the `Tidelift -Subscription`_. Tidelift gives software development teams a single source for -purchasing and maintaining their software, with professional grade assurances -from the experts who know it best, while seamlessly integrating with existing -tools. - -.. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-pylint?utm_source=pypi-pylint&utm_medium=referral&utm_campaign=readme