Documentation for ``pyreverse`` and ``symilar`` (#4992)

* Add documentation for ``pyreverse`` and ``symilar``

* Rephrase "additional tools" to "additional commands" to be consistent with Readme

* Replace some example diagrams with PlantUML ones and fix errors preventing the doc to build

* Incorporate review feedback

* Only hint to the ``-h`` option instead of including all options manually in the docs

6 files changed, 114 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index 61821be25..e3cf47383 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -85,6 +85,10 @@ Release date: TBA
 
 * Fix ``no-self-use`` and ``docparams extension`` for async functions and methods.
 
+* Add documentation for ``pyreverse`` and ``symilar``
+
+  Closes #4616
+
 
 What's New in Pylint 2.10.3?
 ============================
diff --git a/doc/additional_commands/index.rst b/doc/additional_commands/index.rst
new file mode 100644
index 000000000..e4c92cab3
--- /dev/null
+++ b/doc/additional_commands/index.rst
@@ -0,0 +1,109 @@
+
+Additional Commands
+===================
+
+Pylint ships with some additional tools that can be executed from the command line once Pylint itself is installed.
+
+
+Pyreverse
+---------
+
+``pyreverse`` analyzes your source code and generates package and class diagrams.
+It supports output to ``.dot``/``.gv``, ``.vcg`` and ``.puml``/``.plantuml`` (PlantUML) 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
+fed to Graphviz to generate the final image.
+
+Running Pyreverse
+'''''''''''''''''
+
+To run ``pyreverse``, use::
+
+  pyreverse [options] <packages>
+
+<packages> can also be a single Python module.
+To see a full list of the available options, run::
+
+   pyreverse -h
+
+
+Example Output
+''''''''''''''
+
+Example diagrams generated with the ``.puml`` output format are shown below.
+
+Class Diagram
+.............
+
+.. image:: ../media/pyreverse_example_classes.png
+   :width: 625
+   :height: 589
+   :alt: Class diagram generated by pyreverse
+   :align: center
+
+
+Package Diagram
+...............
+
+.. image:: ../media/pyreverse_example_packages.png
+   :width: 344
+   :height: 177
+   :alt: Package diagram generated by pyreverse
+   :align: center
+
+
+Creating Class Diagrams for Specific Classes
+''''''''''''''''''''''''''''''''''''''''''''
+
+In many cases creating a single diagram depicting all classes in the project yields a rather unwieldy, giant diagram.
+While limiting the input path to a single package or module can already help greatly to narrow down the scope, the ``-c`` option
+provides another way to create a class diagram focusing on a single class and its collaborators.
+For example, running::
+
+  pyreverse -ASmy -c pylint.checkers.classes.ClassChecker pylint
+
+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
+   :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
diff --git a/doc/index.rst b/doc/index.rst
index 1e70943d1..1508ff679 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -19,6 +19,7 @@ refactored and can offer you details about the code's complexity.
    how_tos/index.rst
    technical_reference/index.rst
    development_guide/index.rst
+   additional_commands/index.rst
 
    faq
    backlinks
diff --git a/doc/media/ClassChecker_diagram.png b/doc/media/ClassChecker_diagram.png
new file mode 100644
index 000000000..a6a685ce2
--- /dev/null
+++ b/doc/media/ClassChecker_diagram.png
diff --git a/doc/media/pyreverse_example_classes.png b/doc/media/pyreverse_example_classes.png
new file mode 100644
index 000000000..1903aef52
--- /dev/null
+++ b/doc/media/pyreverse_example_classes.png
diff --git a/doc/media/pyreverse_example_packages.png b/doc/media/pyreverse_example_packages.png
new file mode 100644
index 000000000..200b307be
--- /dev/null
+++ b/doc/media/pyreverse_example_packages.png