Split the additional commands documentation in two files (#6641)

Co-authored-by: Daniël van Noord <[email protected]>

Author: Pierre-Sassoulas

doc/conf.py

@@ -62,6 +62,7 @@
     "support": "contact.html",
     "user_guide/ide-integration": "installation.html",
     "user_guide/message-control": "user_guide/messages/message_control.html",
+    "additional_commands/index": "../index.html",
 }
 for m in redirects:
     for r in DIRECTORY_REDIRECT:

doc/index.rst

@@ -37,6 +37,12 @@ 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.
 
+
+Pylint ships with two additional tools:
+
+- :ref:`pyreverse <pyreverse>` (standalone tool that generates package and class diagrams.)
+- :ref:`symilar <symilar>`  (duplicate code finder that is also integrated in pylint)
+
 .. toctree::
    :titlesonly:
    :hidden:
@@ -46,7 +52,8 @@ re-evaluate and re-enable messages as your priorities evolve.
    how_tos/index.rst
    technical_reference/index.rst
    development_guide/index.rst
-   additional_commands/index.rst
+   pyreverse
+   symilar
    faq
    contact
    whatsnew/index.rst

doc/additional_commands/index.rst renamed to doc/pyreverse.rst

@@ -1,14 +1,10 @@
-
-Additional Commands
-===================
-
-Pylint ships with some additional tools that can be executed from the command line once Pylint itself is installed.
-
+.. _pyreverse:
 
 Pyreverse
 ---------
 
 ``pyreverse`` analyzes your source code and generates package and class diagrams.
+
 It supports output to ``.dot``/``.gv``, ``.vcg``, ``.puml``/``.plantuml`` (PlantUML) and ``.mmd``/``.html`` (MermaidJS) file formats.
 If Graphviz (or the ``dot`` command) is installed, all `output formats supported by Graphviz <https://graphviz.org/docs/outputs/>`_
 can be used as well. In this case, ``pyreverse`` first generates a temporary ``.gv`` file, which is then
@@ -35,7 +31,7 @@ Example diagrams generated with the ``.puml`` output format are shown below.
 Class Diagram
 .............
 
-.. image:: ../media/pyreverse_example_classes.png
+.. image:: media/pyreverse_example_classes.png
    :width: 625
    :height: 589
    :alt: Class diagram generated by pyreverse
@@ -45,7 +41,7 @@ Class Diagram
 Package Diagram
 ...............
 
-.. image:: ../media/pyreverse_example_packages.png
+.. image:: media/pyreverse_example_packages.png
    :width: 344
    :height: 177
    :alt: Package diagram generated by pyreverse
@@ -64,46 +60,8 @@ For example, running::
 
 will generate the full class and package diagrams for ``pylint``, but will additionally generate a file ``pylint.checkers.classes.ClassChecker.dot``:
 
-.. image:: ../media/ClassChecker_diagram.png
+.. image:: media/ClassChecker_diagram.png
    :width: 757
    :height: 1452
    :alt: Package diagram generated by pyreverse
    :align: center
-
-
-Symilar
--------
-
-The console script ``symilar`` finds copy pasted blocks in a set of files. It provides a command line interface to the ``Similar`` class, which includes the logic for
-Pylint's ``duplicate-code`` message.
-It can be invoked with::
-
-  symilar [-d|--duplicates min_duplicated_lines] [-i|--ignore-comments] [--ignore-docstrings] [--ignore-imports] [--ignore-signatures] file1...
-
-All files that shall be checked have to be passed in explicitly, e.g.::
-
-  symilar foo.py, bar.py, subpackage/spam.py, subpackage/eggs.py
-
-``symilar`` produces output like the following::
-
-  17 similar lines in 2 files
-  ==tests/data/clientmodule_test.py:3
-  ==tests/data/suppliermodule_test.py:12
-    class Ancestor:
-        """ Ancestor method """
-        __implements__ = (Interface,)
-        cls_member = DoNothing()
-
-        def __init__(self, value):
-            local_variable = 0
-            self.attr = 'this method shouldn\'t have a docstring'
-            self.__value = value
-
-        def get_value(self):
-            """ nice docstring ;-) """
-            return self.__value
-
-        def set_value(self, value):
-            self.__value = value
-            return 'this method shouldn\'t have a docstring'
-  TOTAL lines=58 duplicates=17 percent=29.31

doc/symilar.rst

@@ -0,0 +1,38 @@
+.. _symilar:
+
+Symilar
+-------
+
+The console script ``symilar`` finds copy pasted blocks in a set of files. It provides a command line interface to the ``Similar`` class, which includes the logic for
+Pylint's ``duplicate-code`` message.
+It can be invoked with::
+
+  symilar [-d|--duplicates min_duplicated_lines] [-i|--ignore-comments] [--ignore-docstrings] [--ignore-imports] [--ignore-signatures] file1...
+
+All files that shall be checked have to be passed in explicitly, e.g.::
+
+  symilar foo.py, bar.py, subpackage/spam.py, subpackage/eggs.py
+
+``symilar`` produces output like the following::
+
+  17 similar lines in 2 files
+  ==tests/data/clientmodule_test.py:3
+  ==tests/data/suppliermodule_test.py:12
+    class Ancestor:
+        """ Ancestor method """
+        __implements__ = (Interface,)
+        cls_member = DoNothing()
+
+        def __init__(self, value):
+            local_variable = 0
+            self.attr = 'this method shouldn\'t have a docstring'
+            self.__value = value
+
+        def get_value(self):
+            """ nice docstring ;-) """
+            return self.__value
+
+        def set_value(self, value):
+            self.__value = value
+            return 'this method shouldn\'t have a docstring'
+  TOTAL lines=58 duplicates=17 percent=29.31