[Doc] Create a contact section and cleanup the introduction

.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
 

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] = {
+    # "<source>": "<target>"
+    "intro": "index.html",
+    "support": "contact.html",
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

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

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 [email protected] 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

doc/faq.rst

@@ -6,50 +6,20 @@
 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 ::
 
     git clone https://github.com/PyCQA/pylint
 
 .. _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`

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

doc/requirements.txt

@@ -1,3 +1,4 @@
 Sphinx==4.5.0
+sphinx-reredirects<1
 furo==2022.4.7
 -e .