diff --git a/ChangeLog b/ChangeLog index 0fffa5a0f3..af1d5a55db 100644 --- a/ChangeLog +++ b/ChangeLog @@ -79,6 +79,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 0000000000..e4c92cab30 --- /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 `_ +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] + + 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 1e70943d17..1508ff679e 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 0000000000..a6a685ce2c Binary files /dev/null and b/doc/media/ClassChecker_diagram.png differ diff --git a/doc/media/pyreverse_example_classes.png b/doc/media/pyreverse_example_classes.png new file mode 100644 index 0000000000..1903aef52f Binary files /dev/null and b/doc/media/pyreverse_example_classes.png differ diff --git a/doc/media/pyreverse_example_packages.png b/doc/media/pyreverse_example_packages.png new file mode 100644 index 0000000000..200b307bec Binary files /dev/null and b/doc/media/pyreverse_example_packages.png differ