Reorganize the documentation table of content (#6589)

* [doc] Reorganize the doc table of content with four levels

User, developer, contributor, maintainer.

Co-authored-by: Jacob Walls <[email protected]>

Author: Pierre-Sassoulas

.gitignore

@@ -17,8 +17,8 @@ doc/user_guide/messages/fatal/
 doc/user_guide/messages/information/
 doc/user_guide/messages/refactor/
 doc/user_guide/messages/warning/
-doc/technical_reference/extensions.rst
-doc/technical_reference/features.rst
+doc/user_guide/checkers/extensions.rst
+doc/user_guide/checkers/features.rst
 doc/user_guide/configuration/all-options.rst
 pyve
 build-stamp

doc/conf.py

@@ -43,6 +43,7 @@
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.intersphinx",
     "sphinx_reredirects",
+    "myst_parser",
 ]
 
 
@@ -54,18 +55,44 @@
 # https://readthedocs.org/dashboard/pylint/redirects/
 redirects: dict[str, str] = {
     # "<source>": "<target>"
-    "intro": "index.html",
-    "support": "contact.html",
-    "user_guide/ide-integration": "installation.html",
     "additional_commands/index": "../index.html",
+    "development_guide/index": "api/index.html",
+    "development_guide/contribute": "../development_guide/contributor_guide/index.html",
+    "development_guide/contributor_guide": "contributor_guide/index.html",
+    "development_guide/profiling": "../development_guide/contributor_guide/profiling.html",
+    "development_guide/tests/index": "../contributor_guide/tests/index.html",
+    "development_guide/tests/install": "../contributor_guide/tests/install.html",
+    "development_guide/tests/launching_test": "../contributor_guide/tests/launching_test.html",
+    # There was a typo in the original file, don't fix.
+    "development_guide/tests/writting_test": "../contributor_guide/tests/writing_test.html",
+    "development/testing": "tests/index.html",
+    "how_tos/custom_checkers": "../development_guide/how_tos/custom_checkers.html",
+    "how_tos/index": "../development_guide/how_tos/index.html",
+    "how_tos/plugins": "../development_guide/how_tos/plugins.html",
+    "how_tos/transform_plugins": "../development_guide/how_tos/transform_plugins.html",
+    "intro": "index.html",
     "messages/messages_introduction": "../user_guide/messages/index.html",
     "messages/messages_list": "../user_guide/messages/messages_overview.html",
-    "user_guide/message-control": "messages/message_control.html",
+    "support": "contact.html",
     "technical_reference/c_extensions": "../user_guide/messages/error/no-member.html",
+    "technical_reference/checkers": "../development_guide/technical_reference/checkers.html",
+    "technical_reference/features": "../user_guide/checkers/features.html",
+    "technical_reference/index": "../development_guide/technical_reference/index.html",
+    "technical_reference/startup": "../development_guide/technical_reference/startup.html",
     "user_guide/configuration/naming-styles": "../user_guide/messages/convention/invalid-name.html",
-    "development/testing": "tests/index.html",
+    "user_guide/ide_integration/flymake-emacs": "../installation/ide_integration/flymake-emacs.html",
+    "user_guide/ide_integration/ide-integration": "../installation/ide_integration/index.html",
+    "user_guide/ide-integration": "installation.html",
+    "user_guide/ide_integration/textmate": "../installation/ide_integration/textmate.html",
+    "user_guide/index": "installation/index.html",
+    "user_guide/message-control": "messages/message_control.html",
+    "user_guide/options": "configuration/all-options.html",
+    "user_guide/output": "usage/output.html",
+    "user_guide/pre-commit-integration": "installation/pre-commit-integration.html",
+    "user_guide/run": "usage/run.html",
 }
 
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

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

@@ -0,0 +1,13 @@
+Contributing to pylint
+======================
+
+The contributor guide will help you if you want to contribute to pylint itself.
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   contribute
+   tests/index
+   profiling
+   release

doc/development_guide/contributor_guide/index.rst

@@ -15,4 +15,4 @@ unless they include tests.
 
    install
    launching_test
-   writting_test
+   writing_test

doc/development_guide/profiling.rst renamed to doc/development_guide/contributor_guide/profiling.rst

@@ -14,5 +14,3 @@ Technical Reference
 
   startup
   checkers
-  extensions
-  features

doc/release.md renamed to doc/development_guide/contributor_guide/release.md

@@ -47,12 +47,10 @@ 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", "user_guide", "checkers", "extensions.rst"
     )
     with open(extensions_doc, "w", encoding="utf-8") as stream:
-        stream.write(
-            get_rst_title("Optional Pylint checkers in the extensions module", "=")
-        )
+        stream.write(get_rst_title("Optional checkers", "="))
         stream.write("Pylint provides the following optional plugins:\n\n")
         for module in modules:
             stream.write(f"- :ref:`{module}`\n")

doc/development_guide/tests/index.rst renamed to doc/development_guide/contributor_guide/tests/index.rst

@@ -26,7 +26,7 @@ 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", "user_guide", "checkers", "features.rst")
     with open(features, "w", encoding="utf-8") as stream:
         stream.write("Pylint features\n")
         stream.write("===============\n\n")

doc/development_guide/tests/install.rst renamed to doc/development_guide/contributor_guide/tests/install.rst

@@ -150,7 +150,6 @@ def _write_options_page(options: OptionsDataDict, linter: PyLinter) -> None:
     ) as stream:
         stream.write(
             f"""
-{get_rst_title("All pylint options", "=")}
 
 {sections_string}
 """

doc/development_guide/tests/launching_test.rst renamed to doc/development_guide/contributor_guide/tests/launching_test.rst

@@ -147,7 +147,7 @@ Alternatively, if you use ``pyproject.toml``, e.g.
     ]
 
 See also the :ref:`exhaustive list of possible options
-<user_guide/configuration/all-options:all pylint options>`.
+<all-configurations-options>`.
 
 4.7 Why are there a bunch of messages disabled by default?
 ----------------------------------------------------------
@@ -157,7 +157,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>`.
+<user_guide/checkers/extensions:optional checkers>`.
 
 4.8 I am using another popular linter alongside pylint. Which messages should I disable to avoid duplicates?
 ------------------------------------------------------------------------------------------------------------

doc/development_guide/tests/writting_test.rst renamed to doc/development_guide/contributor_guide/tests/writing_test.rst

@@ -6,12 +6,48 @@
    :hidden:
 
    tutorial
-   user_guide/index.rst
-   how_tos/index.rst
-   technical_reference/index.rst
-   development_guide/index.rst
+
+.. toctree::
+   :caption: User Guide
+   :titlesonly:
+   :hidden:
+
+   user_guide/installation/index
+   user_guide/usage/index
+   user_guide/messages/index
+   user_guide/configuration/index
+   user_guide/checkers/index
+
+.. toctree::
+   :caption: Developer Guide
+   :maxdepth: 2
+   :titlesonly:
+   :hidden:
+
+   development_guide/api/index
+   development_guide/how_tos/index.rst
+   development_guide/technical_reference/index.rst
+   development_guide/contributor_guide/index
+
+.. toctree::
+   :caption: Additional tools
+   :titlesonly:
+   :hidden:
+
    pyreverse
    symilar
+
+.. toctree::
+   :caption: Changelog
+   :titlesonly:
+   :hidden:
+
+   whatsnew/index.rst
+
+.. toctree::
+   :caption: Support
+   :titlesonly:
+   :hidden:
+
    faq
    contact
-   whatsnew/index.rst

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

@@ -1,4 +1,5 @@
 Sphinx==4.5.0
 sphinx-reredirects<1
+myst-parser~=0.16
 furo==2022.4.7
 -e .

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

@@ -0,0 +1,10 @@
+Checkers
+========
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+   :hidden:
+
+   features
+   extensions

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

@@ -0,0 +1,14 @@
+.. _all-configurations-options:
+
+=============
+Configuration
+=============
+
+Pylint is highly configurable. There are a lot of options to follow the needs of
+various projects and a lot of checks to activate if they suit your style.
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   all-options

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

@@ -0,0 +1,36 @@
+.. _installation:
+
+Command line installation
+-------------------------
+
+Pylint is installable using a package manager. Your package manager will find a version that
+works with your interpreter. We recommend ``pip``:
+
+.. code-block:: sh
+
+   pip install pylint
+
+Use the newest Python interpreter if you can.
+
+It's possible to analyse code written for older interpreters by using the ``py-version``
+option and setting it to the old interpreter. For example you can check that there are
+no ``f-strings`` in Python 3.5 code using Python 3.8 with an up-to-date pylint even if
+Python 3.5 is past end of life (EOL).
+
+We do not guarantee that ``py-version`` will work for all EOL python interpreters indefinitely,
+(for anything before python 3.5, it probably won't). If a newer version does not work for you,
+the best available pylint might be an old version that works with your old interpreter but
+without the bug fixes and features of later versions.
+
+.. note::
+    You can also use ``conda`` or your system package manager on debian based OS.
+    These package managers lag a little behind as they are maintained by a separate
+    entity on a slower release cycle.
+
+    .. code-block:: sh
+
+       conda install pylint
+
+    .. code-block:: sh
+
+       sudo apt-get install pylint

doc/development_guide/index.rst

@@ -1,47 +1,11 @@
-.. _installation:
-
-Installation
-============
-
-Command line
-------------
-
-Pylint is installable using a package manager. Your package manager will find a version that
-works with your interpreter. We recommend ``pip``:
-
-.. code-block:: sh
-
-   pip install pylint
-
-Use the newest Python interpreter if you can.
-
-It's possible to analyse code written for older interpreters by using the ``py-version``
-option and setting it to the old interpreter. For example you can check that there are
-no ``f-strings`` in Python 3.5 code using Python 3.8 with an up-to-date pylint even if
-Python 3.5 is past end of life (EOL).
-
-We do not guarantee that ``py-version`` will work for all EOL python interpreters indefinitely,
-(for anything before python 3.5, it's probably not). If a newer version does not work for you,
-the best available pylint might be an old version that works with your old interpreter but
-without the bug fixes and feature of later versions.
-
-NB: You can also use ``conda`` or your system package manager on debian based OS.
-These package managers lag a little behind as they are maintained by a separate
-entity on a slower release cycle.
-
-.. code-block:: sh
-
-   conda install pylint
-
-.. code-block:: sh
-
-   sudo apt-get install pylint
-
+.. _ide-integration:
 
-Editor integration
-------------------
+###########################
+ Editor and IDE integration
+###########################
 
-.. _ide-integration:
+Pylint can be integrated in various editors and IDE's.
+Below you can find tutorials for some of the most common ones.
 
 - Eclipse_
 - Emacs_
@@ -77,3 +41,11 @@ Editor integration
 .. _Visual Studio Code: https://code.visualstudio.com/docs/python/linting#_pylint
 .. _Visual Studio Code Pylint Extension: https://marketplace.visualstudio.com/items?itemName=ms-python.pylint
 .. _WingIDE: https://wingware.com/doc/warnings/external-checkers
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+   :hidden:
+
+   flymake-emacs.rst
+   textmate.rst

doc/technical_reference/checkers.rst renamed to doc/development_guide/technical_reference/checkers.rst

@@ -0,0 +1,18 @@
+Installation
+============
+
+Pylint can be installed:
+
+- As a command line tool
+- Integrated in your editor/ide
+- As a pre-commit hook
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+   :hidden:
+
+   command_line_installation.rst
+   ide_integration/index
+   pre-commit-integration.rst
+   badge