Reorganize the documentation table of content

Create a user guide part and a developper guide part to distinguish the two.

Author: Pierre-Sassoulas

.github/CONTRIBUTING.md

@@ -1,2 +1,2 @@
 Please read the
-[contribute doc](https://github.com/PyCQA/pylint/blob/main/doc/development_guide/contribute.rst).
+[contribute doc](https://github.com/PyCQA/pylint/blob/main/doc/developer_guide/contribute.rst).

.github/PULL_REQUEST_TEMPLATE.md

@@ -5,7 +5,7 @@ To ease the process of reviewing your PR, do make sure to complete the following
 
 - [ ] Add a ChangeLog entry describing what your PR does.
 - [ ] If it's a new feature, or an important bug fix, add a What's New entry in
-      `doc/whatsnew/<current release.rst>`.
+      `doc/user_guide/whatsnew/<current release.rst>`.
 - [ ] Write a good description on what the PR does.
 - [ ] If you used multiple emails or multiple names when contributing, add your mails
    and preferred name in ``script/.contributors_aliases.json``

.gitignore

@@ -9,9 +9,11 @@
 /pylint.egg-info/
 .tox
 *.sw[a-z]
-doc/messages/
-doc/technical_reference/extensions.rst
-doc/technical_reference/features.rst
+doc/user_guide/messages/
+!doc/user_guide/messages/*.rst
+!doc/user_guide/messages/index.rst
+doc/developer_guide/technical_reference/extensions.rst
+doc/developer_guide/technical_reference/features.rst
 doc/user_guide/configuration/all-options.rst
 pyve
 build-stamp

.pre-commit-config.yaml

@@ -79,7 +79,7 @@ repos:
         entry: python3 -m script.fix_documentation
         language: system
         types: [text]
-        files: ^(ChangeLog|doc/whatsnew/\d+\.\d+\.rst)
+        files: ^(ChangeLog|doc/user_guide/whatsnew/\d+\.\d+\.rst)
   - repo: https://github.com/myint/rstcheck
     rev: "v5.0.0"
     hooks:

ChangeLog

@@ -8,7 +8,7 @@ What's New in Pylint 2.14.0?
 Release date: TBA
 
 ..
-  Put new features here and also in 'doc/whatsnew/2.14.rst'
+  Put new features here and also in 'doc/user_guide/whatsnew/2.14.rst'
 
 * We have improved our recognition of inline disable and enable comments. It is
   now possible to disable ``bad-option-value`` inline  (as long as you disable it before

doc/whatsnew/changelog.rst renamed to doc/developer_guide/changelog.rst

@@ -85,7 +85,7 @@ of Pylint as it gives you access to the latest ``ast`` parser.
   (`What's New` section). For the release document we usually write some more details,
   and it is also a good place to offer examples on how the new change is supposed to work.
 
-- Add a short entry in :file:`doc/whatsnew/VERSION.rst`.
+- Add a short entry in :file:`doc/user_guide/whatsnew/VERSION.rst`.
 
 - If you used multiple emails or multiple names when contributing, add your mails
   and preferred name in the ``script/.contributors_aliases.json`` file.

doc/development_guide/contribute.rst renamed to doc/developer_guide/contribute.rst

@@ -0,0 +1,22 @@
+Developer Guide
+===============
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   contribute
+   testing
+   how_tos/index.rst
+   technical_reference/index.rst
+   profiling
+
+Changelog
+=========
+
+The "Changelog" contains *all* nontrivial changes to Pylint for the current version.
+
+.. toctree::
+   :maxdepth: 2
+
+   changelog.rst

doc/how_tos/custom_checkers.rst renamed to doc/developer_guide/how_tos/custom_checkers.rst

@@ -47,7 +47,7 @@ def builder_inited(app: Optional[Sphinx]) -> None:
     linter.load_plugin_modules(modules)
 
     extensions_doc = os.path.join(
-        base_path, "doc", "technical_reference", "extensions.rst"
+        base_path, "doc", "developer_guide", "technical_reference", "extensions.rst"
     )
     with open(extensions_doc, "w", encoding="utf-8") as stream:
         stream.write(

doc/how_tos/index.rst renamed to doc/developer_guide/how_tos/index.rst

@@ -24,7 +24,9 @@ def builder_inited(app: Optional[Sphinx]) -> None:
     )
     linter = PyLinter()
     linter.load_default_plugins()
-    features = os.path.join(base_path, "doc", "technical_reference", "features.rst")
+    features = os.path.join(
+        base_path, "doc", "developer_guide", "technical_reference", "features.rst"
+    )
     with open(features, "w", encoding="utf-8") as stream:
         stream.write("Pylint features\n")
         stream.write("===============\n\n")

doc/how_tos/plugins.rst renamed to doc/developer_guide/how_tos/plugins.rst

@@ -23,7 +23,7 @@
 PYLINT_BASE_PATH = Path(__file__).resolve().parent.parent.parent
 """Base path to the project folder."""
 
-PYLINT_MESSAGES_PATH = PYLINT_BASE_PATH / "doc" / "messages"
+PYLINT_MESSAGES_PATH = PYLINT_BASE_PATH / "doc" / "user_guide" / "messages"
 """Path to the messages documentation folder."""
 
 PYLINT_MESSAGES_DATA_PATH = PYLINT_BASE_PATH / "doc" / "data" / "messages"

doc/how_tos/transform_plugins.rst renamed to doc/developer_guide/how_tos/transform_plugins.rst

@@ -242,7 +242,7 @@ they are prone to false positives or that they are opinionated enough
 for not being included as default messages.
 
 You can see the plugin you need to explicitly :ref:`load in the technical reference
-<technical_reference/extensions:optional pylint checkers in the extensions module>`.
+<developer_guide/technical_reference/extensions:optional pylint checkers in the extensions module>`.
 
 4.8 I am using another popular linter alongside pylint. Which messages should I disable to avoid duplicates?
 ------------------------------------------------------------------------------------------------------------

doc/developer_guide/index.rst

@@ -1,6 +1,5 @@
-
-Pylint User Manual
-==================
+Pylint documentation
+====================
 
 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
@@ -13,16 +12,7 @@ refactored and can offer you details about the code's complexity.
    :titlesonly:
 
    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
-
+   developer_guide/index.rst
    faq
-   backlinks
    support
-   whatsnew/index.rst