[doc] Reorganize the doc table of content with foor levels of guide

User, developper, contributor, maintainer.

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/configuration/extensions.rst
+doc/user_guide/configuration/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",
 ]
 
 
@@ -63,6 +64,23 @@
     "user_guide/message-control": "messages/message_control.html",
     "technical_reference/c_extensions": "../user_guide/c_extensions.html",
     "development/testing": "tests/index.html",
+    "development_guide/contribute": "../development_guide/contributor_guide/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",
+    "technical_reference/checkers": "../development_guide/technical_reference/checkers.html",
+    "technical_reference/index": "../development_guide/technical_reference/index.html",
+    "technical_reference/startup": "../development_guide/technical_reference/startup.html",
+    "technical_reference/features": "../user_guide/configuration/features.html",
+    "user_guide/options": "configuration/index.html",
+    "user_guide/ide_integration/ide-integration": "index.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_guide/contributor_guide": "contributor_guide/index.html",
 }
 
 # Add any paths that contain templates here, relative to this directory.

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

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

doc/development_guide/contributor_guide/index.rst

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

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

@@ -1,11 +1,18 @@
-Development
-===========
+===============
+Developer guide
+===============
+
+The developer guide will help you with development around pylint,
+launching pylint programmatically, creating custom plugins,
+creating custom checkers, but also contain the contributor guide
+if you want to contribute to pylint itself.
 
 .. toctree::
    :maxdepth: 2
    :titlesonly:
 
-   contribute
-   tests/index
+   how_tos/index.rst
+   technical_reference/index.rst
    api/index
    profiling
+   contributor_guide/index

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

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

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

@@ -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", "configuration", "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 Pylint 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/launching_test.rst renamed to doc/development_guide/contributor_guide/tests/launching_test.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", "user_guide", "configuration", "features.rst"
+    )
     with open(features, "w", encoding="utf-8") as stream:
         stream.write("Pylint features\n")
         stream.write("===============\n\n")

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

@@ -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/configuration/extensions:optional Pylint checkers>`.
 
 4.8 I am using another popular linter alongside pylint. Which messages should I disable to avoid duplicates?
 ------------------------------------------------------------------------------------------------------------

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

@@ -7,8 +7,6 @@
 
    tutorial
    user_guide/index.rst
-   how_tos/index.rst
-   technical_reference/index.rst
    development_guide/index.rst
    pyreverse
    symilar

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

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

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

@@ -0,0 +1,15 @@
+=============
+Configuration
+=============
+
+Pylint is highly configurable. There's a lot of options to follow the need of
+every projects and a lot of checks to activate if they suit your style.
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   all-options
+   features
+   extensions
+   naming-styles

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

@@ -0,0 +1,51 @@
+.. _ide-integration:
+
+###########################
+ Editor and 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_
+- `Eric IDE`_ in the `Project > Check` menu,
+- gedit_ (`another option for gedit`_)
+- :ref:`Flymake <pylint_in_flymake>`
+- `Jupyter Notebook`_
+- Komodo_
+- `Pycharm`_
+- PyDev_
+- pyscripter_ in the `Tool -> Tools` menu.
+- Spyder_ in the `View -> Panes -> Static code analysis`
+- :ref:`TextMate <pylint_in_textmate>`
+- Vim_
+- `Visual Studio Code`_ in the `Preferences -> Settings` menu
+- `Visual Studio Code Pylint Extension`_
+- `Visual Studio`_ in the `Python > Run PyLint` command on a project's context menu.
+- WingIDE_
+
+.. _Eclipse: https://www.pydev.org/manual_adv_pylint.html
+.. _Emacs: https://www.emacswiki.org/emacs/PythonProgrammingInEmacs
+.. _Eric IDE: https://eric-ide.python-projects.org/
+.. _gedit: https://launchpad.net/gedit-pylint-2
+.. _another option for gedit: https://wiki.gnome.org/Apps/Gedit/PylintPlugin
+.. _Jupyter Notebook:  https://github.com/nbQA-dev/nbQA
+.. _Komodo: https://mateusz.loskot.net/post/2006/01/15/running-pylint-from-komodo/
+.. _Pycharm: https://stackoverflow.com/a/46409649/2519059
+.. _pydev: https://www.pydev.org/manual_adv_pylint.html
+.. _pyscripter: https://github.com/pyscripter/pyscripter
+.. _spyder: https://docs.spyder-ide.org/current/panes/pylint.html
+.. _Vim: https://www.vim.org/scripts/script.php?script_id=891
+.. _Visual Studio: https://docs.microsoft.com/visualstudio/python/code-pylint
+.. _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/development_guide/index.rst

@@ -7,11 +7,12 @@ User Guide
    :titlesonly:
 
    installation
+   ide_integration/index
    run
    output
    c_extensions
    messages/index
-   options
-   ide_integration/ide-integration
+   configuration/index
+
    pre-commit-integration
    badge

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

@@ -36,44 +36,3 @@ entity on a slower release cycle.
 .. code-block:: sh
 
    sudo apt-get install pylint
-
-
-Editor integration
-------------------
-
-.. _ide-integration:
-
-- Eclipse_
-- Emacs_
-- `Eric IDE`_ in the `Project > Check` menu,
-- gedit_ (`another option for gedit`_)
-- :ref:`Flymake <pylint_in_flymake>`
-- `Jupyter Notebook`_
-- Komodo_
-- `Pycharm`_
-- PyDev_
-- pyscripter_ in the `Tool -> Tools` menu.
-- Spyder_ in the `View -> Panes -> Static code analysis`
-- :ref:`TextMate <pylint_in_textmate>`
-- Vim_
-- `Visual Studio Code`_ in the `Preferences -> Settings` menu
-- `Visual Studio Code Pylint Extension`_
-- `Visual Studio`_ in the `Python > Run PyLint` command on a project's context menu.
-- WingIDE_
-
-.. _Eclipse: https://www.pydev.org/manual_adv_pylint.html
-.. _Emacs: https://www.emacswiki.org/emacs/PythonProgrammingInEmacs
-.. _Eric IDE: https://eric-ide.python-projects.org/
-.. _gedit: https://launchpad.net/gedit-pylint-2
-.. _another option for gedit: https://wiki.gnome.org/Apps/Gedit/PylintPlugin
-.. _Jupyter Notebook:  https://github.com/nbQA-dev/nbQA
-.. _Komodo: https://mateusz.loskot.net/post/2006/01/15/running-pylint-from-komodo/
-.. _Pycharm: https://stackoverflow.com/a/46409649/2519059
-.. _pydev: https://www.pydev.org/manual_adv_pylint.html
-.. _pyscripter: https://github.com/pyscripter/pyscripter
-.. _spyder: https://docs.spyder-ide.org/current/panes/pylint.html
-.. _Vim: https://www.vim.org/scripts/script.php?script_id=891
-.. _Visual Studio: https://docs.microsoft.com/visualstudio/python/code-pylint
-.. _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