diff options
author | Andreas Finkler <3929834+DudeNr33@users.noreply.github.com> | 2021-09-11 21:37:27 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-09-11 21:37:27 +0200 |
commit | ebae36e35447f113649b87a5dd7a3e03b793605c (patch) | |
tree | 71be41c1bb261a5e78dd52f5367ef214170f0ce1 | |
parent | dcd488756677fdbac3a8d56c3b1f6c09ddd0d300 (diff) | |
download | pylint-git-ebae36e35447f113649b87a5dd7a3e03b793605c.tar.gz |
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
-rw-r--r-- | ChangeLog | 4 | ||||
-rw-r--r-- | doc/additional_commands/index.rst | 109 | ||||
-rw-r--r-- | doc/index.rst | 1 | ||||
-rw-r--r-- | doc/media/ClassChecker_diagram.png | bin | 0 -> 138128 bytes | |||
-rw-r--r-- | doc/media/pyreverse_example_classes.png | bin | 0 -> 30114 bytes | |||
-rw-r--r-- | doc/media/pyreverse_example_packages.png | bin | 0 -> 6221 bytes |
6 files changed, 114 insertions, 0 deletions
@@ -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 Binary files differnew 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 Binary files differnew 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 Binary files differnew file mode 100644 index 000000000..200b307be --- /dev/null +++ b/doc/media/pyreverse_example_packages.png |