From 2d3853fa30afe59dab85457f037849a7c3eeda24 Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Wed, 18 May 2022 12:38:02 +0200 Subject: [PATCH 1/3] [doc] Move the additional command section to user guide --- doc/conf.py | 1 + doc/index.rst | 9 +++- .../index.rst => pyreverse.rst} | 52 ++----------------- doc/symilar.rst | 38 ++++++++++++++ 4 files changed, 52 insertions(+), 48 deletions(-) rename doc/{additional_commands/index.rst => pyreverse.rst} (54%) create mode 100644 doc/symilar.rst diff --git a/doc/conf.py b/doc/conf.py index 25f0364b41..1c74b19fb0 100644 --- a/doc/conf.py +++ b/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: diff --git a/doc/index.rst b/doc/index.rst index df9a4c133e..9faf0dd7a4 100644 --- a/doc/index.rst +++ b/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 ` (standalone that generates package and class diagrams.) +- :ref:`symilar ` (duplicate code finder 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 diff --git a/doc/additional_commands/index.rst b/doc/pyreverse.rst similarity index 54% rename from doc/additional_commands/index.rst rename to doc/pyreverse.rst index b8ebb15cb6..fecbbaf5a8 100644 --- a/doc/additional_commands/index.rst +++ b/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 `_ 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 diff --git a/doc/symilar.rst b/doc/symilar.rst new file mode 100644 index 0000000000..5b75ff38f2 --- /dev/null +++ b/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 From 956fffe5d010f08f03cfcb80ce13a9d8acf34435 Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Thu, 19 May 2022 09:10:00 +0200 Subject: [PATCH 2/3] Update doc/conf.py MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Daniël van Noord <13665637+DanielNoord@users.noreply.github.com> --- doc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 1c74b19fb0..7b0fd30a4d 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -62,7 +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", + "additional_commands/index": "../index.html", } for m in redirects: for r in DIRECTORY_REDIRECT: From 6aa7992b28583ef5688205e379f77ab398dd61bb Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Thu, 19 May 2022 09:26:39 +0200 Subject: [PATCH 3/3] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Daniël van Noord <13665637+DanielNoord@users.noreply.github.com> --- doc/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 9faf0dd7a4..555035f03b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -40,8 +40,8 @@ re-evaluate and re-enable messages as your priorities evolve. Pylint ships with two additional tools: -- :ref:`pyreverse ` (standalone that generates package and class diagrams.) -- :ref:`symilar ` (duplicate code finder also integrated in pylint) +- :ref:`pyreverse ` (standalone tool that generates package and class diagrams.) +- :ref:`symilar ` (duplicate code finder that is also integrated in pylint) .. toctree:: :titlesonly: