Skip to content

Commit 52138e9

Browse files
Pierre-SassoulasDanielNoord
Pierre-Sassoulas
and
DanielNoord
authored
[Doc] Create a contact section and cleanup the introduction (#6613)
* Add a mechanism for redirection * Upgrade cache so the new requirements are properly installed Co-authored-by: Daniël van Noord <[email protected]>
1 parent 39f95c0 commit 52138e9

File tree

10 files changed

+122
-201
lines changed

10 files changed

+122
-201
lines changed

‎.github/workflows/checks.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ on:
99

1010
env:
1111
# Also change CACHE_VERSION in the other workflows
12-
CACHE_VERSION: 6
12+
CACHE_VERSION: 7
1313
DEFAULT_PYTHON: 3.8
1414
PRE_COMMIT_CACHE: ~/.cache/pre-commit
1515

‎doc/backlinks.rst

-14
This file was deleted.

‎doc/conf.py

+21-10
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,7 @@
22
# For details: https://github.com/PyCQA/pylint/blob/main/LICENSE
33
# Copyright (c) https://github.com/PyCQA/pylint/blob/main/CONTRIBUTORS.txt
44

5-
# Pylint documentation build configuration file, created by
6-
# sphinx-quickstart on Thu Apr 4 20:31:25 2013.
7-
#
8-
# This file is execfile()d with the current directory set to its containing dir.
9-
#
10-
# Note that not all possible configuration values are present in this
11-
# autogenerated file.
12-
#
13-
# All configuration values have a default; values that are commented out
14-
# serve to show the default.
5+
from __future__ import annotations
156

167
import os
178
import sys
@@ -24,6 +15,18 @@
2415
# The short X.Y version.
2516
from pylint import __version__
2617

18+
# Pylint documentation build configuration file, created by
19+
# sphinx-quickstart on Thu Apr 4 20:31:25 2013.
20+
#
21+
# This file is execfile()d with the current directory set to its containing dir.
22+
#
23+
# Note that not all possible configuration values are present in this
24+
# autogenerated file.
25+
#
26+
# All configuration values have a default; values that are commented out
27+
# serve to show the default.
28+
29+
2730
# If extensions (or modules to document with autodoc) are in another directory,
2831
# add these directories to sys.path here. If the directory is relative to the
2932
# documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -43,8 +46,16 @@
4346
"pylint_options",
4447
"sphinx.ext.autosectionlabel",
4548
"sphinx.ext.intersphinx",
49+
"sphinx_reredirects",
4650
]
4751

52+
# https://documatt.gitlab.io/sphinx-reredirects/usage.html
53+
redirects: dict[str, str] = {
54+
# "<source>": "<target>"
55+
"intro": "index.html",
56+
"support": "contact.html",
57+
}
58+
4859
# Add any paths that contain templates here, relative to this directory.
4960
templates_path = ["_templates"]
5061

‎doc/contact.rst

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
Contact
2+
=======
3+
4+
Bug reports, feedback
5+
---------------------
6+
.. _bug reports, feedback:
7+
8+
You think you have found a bug in Pylint? Well, this may be the case
9+
since Pylint and Python are under heavy development!
10+
11+
Please take the time to check if it is already in the issue tracker at
12+
https://github.com/PyCQA/pylint
13+
14+
Note that the issue might also be reported in one of Pylint's major dependencies,
15+
astroid:
16+
17+
* https://github.com/PyCQA/astroid
18+
19+
Discord server
20+
--------------
21+
22+
You can discuss your problem using the discord server:
23+
24+
https://discord.com/invite/Egy6P8AMB5
25+
26+
Mailing lists
27+
-------------
28+
29+
.. _Mailing lists:
30+
31+
The code-quality mailing list is shared with other tools that aim
32+
at improving the quality of python code.
33+
34+
You can subscribe to this mailing list at
35+
https://mail.python.org/mailman3/lists/code-quality.python.org/
36+
37+
Archives are available at
38+
https://mail.python.org/pipermail/code-quality/
39+
40+
Archives before April 2013 are available at
41+
https://lists.logilab.org/pipermail/python-projects/
42+
43+
Support
44+
-------
45+
46+
.. image:: media/Tidelift_Logos_RGB_Tidelift_Shorthand_On-White.png
47+
:height: 150
48+
:alt: Tidelift
49+
:align: left
50+
:class: tideliftlogo
51+
52+
Professional support for pylint is available as part of the `Tidelift
53+
Subscription`_. Tidelift gives software development teams a single source for
54+
purchasing and maintaining their software, with professional grade assurances
55+
from the experts who know it best, while seamlessly integrating with existing
56+
tools.
57+
58+
.. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-pylint?utm_source=pypi-pylint&utm_medium=referral&utm_campaign=readme

‎doc/development_guide/contribute.rst

-45
Original file line numberDiff line numberDiff line change
@@ -4,51 +4,6 @@
44
Contributing
55
==============
66

7-
.. _bug reports, feedback:
8-
9-
Bug reports, feedback
10-
---------------------
11-
12-
You think you have found a bug in Pylint? Well, this may be the case
13-
since Pylint is under heavy development!
14-
15-
Please take the time to check if it is already in the issue tracker at
16-
https://github.com/PyCQA/pylint
17-
18-
If you cannot find it in the tracker, create a new issue there or discuss your
19-
problem on the [email protected] mailing list or using the discord
20-
server https://discord.com/invite/Egy6P8AMB5.
21-
22-
The code-quality mailing list is also a nice place to provide feedback about
23-
Pylint, since it is shared with other tools that aim at improving the quality of
24-
python code.
25-
26-
Note that if you don't find something you have expected in Pylint's issue
27-
tracker, it may be because it is an issue with one of its dependencies, namely
28-
astroid:
29-
30-
* https://github.com/PyCQA/astroid
31-
32-
.. _Mailing lists:
33-
34-
Discord server
35-
--------------
36-
37-
https://discord.com/invite/Egy6P8AMB5
38-
39-
Mailing lists
40-
-------------
41-
42-
You can subscribe to this mailing list at
43-
https://mail.python.org/mailman3/lists/code-quality.python.org/
44-
45-
Archives are available at
46-
https://mail.python.org/pipermail/code-quality/
47-
48-
Archives before April 2013 are available at
49-
https://lists.logilab.org/pipermail/python-projects/
50-
51-
527
.. _repository:
538

549
Repository

‎doc/faq.rst

+4-44
Original file line numberDiff line numberDiff line change
@@ -6,50 +6,20 @@
66
Frequently Asked Questions
77
==========================
88

9-
1. About Pylint
10-
===============
11-
12-
1.1 What is Pylint?
13-
--------------------
14-
15-
Pylint is a `static code checker`_, meaning it can analyse your code without
16-
actually running it. Pylint checks for errors, tries to enforce a coding
17-
standard, and tries to enforce a coding style.
18-
19-
.. _`static code checker`: https://en.wikipedia.org/wiki/Static_code_analysis
20-
21-
22-
2. Installation
23-
===============
24-
25-
2.1 How do I install Pylint?
26-
----------------------------
9+
How do I install Pylint?
10+
------------------------
2711

2812
Everything should be explained on :ref:`installation`.
2913

30-
2.2 What kind of versioning system does Pylint use?
31-
---------------------------------------------------
14+
What kind of versioning system does Pylint use?
15+
-----------------------------------------------
3216

3317
Pylint uses git. To get the latest version of Pylint from the repository, simply invoke ::
3418

3519
git clone https://github.com/PyCQA/pylint
3620

3721
.. _git: https://git-scm.com/
3822

39-
2.3 What are Pylint's dependencies?
40-
-----------------------------------
41-
42-
Pylint depends on astroid_ and a couple of other packages.
43-
See the following section for details on what versions of Python are
44-
supported.
45-
46-
.. _`astroid`: https://github.com/PyCQA/astroid
47-
48-
2.4 What versions of Python is Pylint supporting?
49-
-------------------------------------------------
50-
51-
The supported running environment since Pylint 2.14.0 is Python 3.7.2+.
52-
5323

5424
3. Running Pylint
5525
=================
@@ -303,13 +273,3 @@ Pylint, you can set ``evaluation`` to the above expression to get the new
303273
behavior. Likewise, since negative values are still technically supported,
304274
``evaluation`` can be set to a version of the above expression that does not
305275
enforce a floor of zero.
306-
307-
6.2 I think I found a bug in Pylint. What should I do?
308-
-------------------------------------------------------
309-
310-
Read :ref:`Bug reports, feedback`
311-
312-
6.3 I have a question about Pylint that isn't answered here.
313-
------------------------------------------------------------
314-
315-
Read :ref:`Mailing lists`

‎doc/index.rst

+37-12
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,53 @@
1+
Pylint documentation
2+
====================
13

2-
Pylint User Manual
3-
==================
4+
Pylint is a `static code analyser`_ for Python 2 or 3. The latest version supports Python
5+
3.7.2 and above.
46

5-
Pylint is a tool that checks for errors in Python code, tries to enforce a
6-
coding standard and looks for code smells. It can also look for certain type
7-
errors, it can recommend suggestions about how particular blocks can be
8-
refactored and can offer you details about the code's complexity.
7+
Pylint analyses your code without actually running it. It checks for errors, enforces a coding
8+
standard, looks for `code smells`_, and can make suggestions about how the code could be refactored.
99

10+
Projects that you might want to use alongside pylint include flake8_ (faster and simpler checks
11+
with very few false positives), mypy_, pyright_ or pyre_ (typing checks), bandit_ (security
12+
oriented checks), black_ and isort_ (auto-formatting), autoflake_ (automated removal of
13+
unused import or variable), pyupgrade_ (automated upgrade to newer python syntax) and
14+
pydocstringformatter_ (automated pep257).
15+
16+
.. _flake8: https://gitlab.com/pycqa/flake8/
17+
.. _bandit: https://github.com/PyCQA/bandit
18+
.. _mypy: https://github.com/python/mypy
19+
.. _pyright: https://github.com/microsoft/pyright
20+
.. _pyre: https://github.com/facebook/pyre-check
21+
.. _black: https://github.com/psf/black
22+
.. _autoflake: https://github.com/myint/autoflake
23+
.. _pyupgrade: https://github.com/asottile/pyupgrade
24+
.. _pydocstringformatter: https://github.com/DanielNoord/pydocstringformatter
25+
.. _isort: https://pycqa.github.io/isort/
26+
.. _`static code analyser`: https://en.wikipedia.org/wiki/Static_code_analysis
27+
.. _`code smells`: https://martinfowler.com/bliki/CodeSmell.html
28+
29+
Pylint can infer actual values from your code using its internal code representation (astroid).
30+
If your code is ``import logging as argparse``, Pylint will know that ``argparse.error(...)``
31+
is in fact a logging call and not an argparse call.
32+
33+
Pylint isn't smarter than you: it may warn you about things that you have
34+
conscientiously done or checks for some things that you don't care about.
35+
During adoption, especially in a legacy project where pylint was never enforced,
36+
it's best to start with the ``--errors-only`` flag, then disable
37+
convention and refactor message with ``--disable=C,R`` and progressively
38+
re-evaluate and re-enable messages as your priorities evolve.
1039

1140
.. toctree::
12-
:maxdepth: 2
1341
:titlesonly:
42+
:hidden:
1443

15-
intro
1644
tutorial
17-
1845
user_guide/index.rst
1946
how_tos/index.rst
2047
messages/index.rst
2148
technical_reference/index.rst
2249
development_guide/index.rst
2350
additional_commands/index.rst
24-
2551
faq
26-
backlinks
27-
support
52+
contact
2853
whatsnew/index.rst

‎doc/intro.rst

-58
This file was deleted.

‎doc/requirements.txt

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
Sphinx==4.5.0
2+
sphinx-reredirects<1
23
furo==2022.4.7
34
-e .

0 commit comments

Comments
 (0)