From 614f80e330e30033dd1614187d88b06aa98a1ff3 Mon Sep 17 00:00:00 2001 From: Julfried <51880314+Julfried@users.noreply.github.com> Date: Mon, 11 Nov 2024 09:28:35 +0100 Subject: [PATCH] Improve pyreverse documentation (#10063) Co-authored-by: Pierre Sassoulas --- .../pyreverse/configuration.rst | 77 +++++++++++------ doc/additional_tools/pyreverse/index.rst | 84 ++++++------------- .../pyreverse/output_examples.rst | 40 +++++++++ doc/exts/pyreverse_configuration.py | 34 ++++++-- doc/index.rst | 1 + 5 files changed, 146 insertions(+), 90 deletions(-) create mode 100644 doc/additional_tools/pyreverse/output_examples.rst diff --git a/doc/additional_tools/pyreverse/configuration.rst b/doc/additional_tools/pyreverse/configuration.rst index aa42e8c9a5..845386e533 100644 --- a/doc/additional_tools/pyreverse/configuration.rst +++ b/doc/additional_tools/pyreverse/configuration.rst @@ -2,37 +2,53 @@ .. docs extension in 'doc/exts/pyreverse_configuration.py'. +Usage +##### -Pyreverse Configuration -^^^^^^^^^^^^^^^^^^^^^^^ +``pyreverse`` is run from the command line using the following syntax:: + + pyreverse [options] + +where ```` is one or more Python packages or modules to analyze. + +The available options are organized into the following categories: + +* :ref:`filtering-and-scope` - Control which classes and relationships appear in your diagrams +* :ref:`display-options` - Customize the visual appearance including colors and labels +* :ref:`output-control` - Select output formats and set the destination directory +* :ref:`project-configuration` - Define project settings like source roots and ignored files + + +.. _filtering-and-scope: Filtering and Scope -------------------- +=================== + --all-ancestors -""""""""""""""" +--------------- *Show all ancestors of all classes in .* **Default:** ``None`` --all-associated -"""""""""""""""" +---------------- *Show all classes associated with the target classes, including indirect associations.* **Default:** ``None`` --class -""""""" +------- *Create a class diagram with all classes related to ; this uses by default the options -ASmy* **Default:** ``None`` --filter-mode -""""""""""""" +------------- *Filter attributes and functions according to . Correct modes are: 'PUB_ONLY' filter all non public attributes [DEFAULT], equivalent to PRIVATE+SPECIAL 'ALL' no filter @@ -43,28 +59,28 @@ Filtering and Scope --show-ancestors -"""""""""""""""" +---------------- *Show generations of ancestor classes not in .* **Default:** ``None`` --show-associated -""""""""""""""""" +----------------- *Show levels of associated classes not in .* **Default:** ``None`` --show-builtin -"""""""""""""" +-------------- *Include builtin objects in representation of classes.* **Default:** ``False`` --show-stdlib -""""""""""""" +------------- *Include standard library objects in representation of classes.* **Default:** ``False`` @@ -72,46 +88,49 @@ Filtering and Scope +.. _display-options: + Display Options ---------------- +=============== + --color-palette -""""""""""""""" +--------------- *Comma separated list of colors to use for the package depth coloring.* **Default:** ``('#77AADD', '#99DDFF', '#44BB99', '#BBCC33', '#AAAA00', '#EEDD88', '#EE8866', '#FFAABB', '#DDDDDD')`` --colorized -""""""""""" +----------- *Use colored output. Classes/modules of the same package get the same color.* **Default:** ``False`` --max-color-depth -""""""""""""""""" +----------------- *Use separate colors up to package depth of . Higher depths will reuse colors.* **Default:** ``2`` --module-names -"""""""""""""" +-------------- *Include module name in the representation of classes.* **Default:** ``None`` --no-standalone -""""""""""""""" +--------------- *Only show nodes with connections.* **Default:** ``False`` --only-classnames -""""""""""""""""" +----------------- *Don't show attributes and methods in the class boxes; this disables -f values.* **Default:** ``False`` @@ -119,18 +138,21 @@ Display Options +.. _output-control: + Output Control --------------- +============== + --output -"""""""" +-------- *Create a *. output file if format is available. Available formats are: .dot, .puml, .plantuml, .mmd, .html. Any other format will be tried to be created by using the 'dot' command line tool, which requires a graphviz installation. In this case, these additional formats are available (see `Graphviz output formats `_).* **Default:** ``dot`` --output-directory -"""""""""""""""""" +------------------ *Set the output directory path.* **Default:** ``""`` @@ -138,32 +160,35 @@ Output Control +.. _project-configuration: + Project Configuration ---------------------- +===================== + --ignore -"""""""" +-------- *Files or directories to be skipped. They should be base names, not paths.* **Default:** ``('CVS',)`` --project -""""""""" +--------- *Set the project name. This will later be appended to the output file names.* **Default:** ``""`` --source-roots -"""""""""""""" +-------------- *Add paths to the list of the source roots. Supports globbing patterns. The source root is an absolute path or a path relative to the current working directory used to determine a package namespace for modules located under the source root.* **Default:** ``()`` --verbose -""""""""" +--------- *Makes pyreverse more verbose/talkative. Mostly useful for debugging.* **Default:** ``False`` diff --git a/doc/additional_tools/pyreverse/index.rst b/doc/additional_tools/pyreverse/index.rst index 41f74731dc..4dc8a9b4b1 100644 --- a/doc/additional_tools/pyreverse/index.rst +++ b/doc/additional_tools/pyreverse/index.rst @@ -1,72 +1,40 @@ .. _pyreverse: +========= Pyreverse ---------- +========= -``pyreverse`` analyzes your source code and generates package and class diagrams. +``pyreverse`` is a powerful tool that creates UML diagrams from your Python code. It helps you visualize: -It supports output to ``.dot``/``.gv``, ``.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 -fed to Graphviz to generate the final image. +- Package dependencies and structure +- Class hierarchies and relationships +- Method and attribute organization -Running Pyreverse -''''''''''''''''' +Output Formats +============== -To run ``pyreverse``, use:: +``pyreverse`` supports multiple output formats: - pyreverse [options] +* Native formats: + * ``.dot``/``.gv`` (Graphviz) + * ``.puml``/``.plantuml`` (PlantUML) + * ``.mmd``/``.html`` (MermaidJS) - can also be a single Python module. -To see a full list of the available options, run:: +* Additional formats (requires Graphviz installation): + * All `Graphviz output formats `_ (PNG, SVG, PDF, etc.) + * ``pyreverse`` first generates a temporary ``.gv`` file, which is then fed to Graphviz to generate the final image - pyreverse -h +Getting Started +=============== -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 +Check out the :doc:`configuration` guide to learn about available options, or see :doc:`output_examples` +for sample diagrams and common use cases. .. toctree:: - :maxdepth: 1 - :hidden: + :maxdepth: 2 + :caption: Pyreverse + :titlesonly: + :hidden: - configuration + configuration + output_examples diff --git a/doc/additional_tools/pyreverse/output_examples.rst b/doc/additional_tools/pyreverse/output_examples.rst new file mode 100644 index 0000000000..32fdfc8f07 --- /dev/null +++ b/doc/additional_tools/pyreverse/output_examples.rst @@ -0,0 +1,40 @@ +Example Output +############## + +Example diagrams generated with the ``.puml`` output format are shown below. + +Package Diagram +............... + +.. image:: ../../media/pyreverse_example_packages.png + :width: 344 + :height: 177 + :alt: Package diagram generated by pyreverse + :align: center + +Class Diagram +............. + +.. image:: ../../media/pyreverse_example_classes.png + :width: 625 + :height: 589 + :alt: Class 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 diff --git a/doc/exts/pyreverse_configuration.py b/doc/exts/pyreverse_configuration.py index f4d77ef216..f4dde54357 100644 --- a/doc/exts/pyreverse_configuration.py +++ b/doc/exts/pyreverse_configuration.py @@ -30,16 +30,32 @@ class OptionsData(NamedTuple): def _write_config_page(run: Run) -> None: """Create or overwrite the configuration page.""" sections: list[str] = [ - ".. This file is auto-generated. Make any changes to the associated\n" - ".. docs extension in 'doc/exts/pyreverse_configuration.py'.\n\n", - get_rst_title("Pyreverse Configuration", "^"), - ] + f"""\ +.. This file is auto-generated. Make any changes to the associated +.. docs extension in 'doc/exts/pyreverse_configuration.py'. + + +{get_rst_title("Usage", "#")} + +``pyreverse`` is run from the command line using the following syntax:: + + pyreverse [options] +where ```` is one or more Python packages or modules to analyze. + +The available options are organized into the following categories: + +* :ref:`filtering-and-scope` - Control which classes and relationships appear in your diagrams +* :ref:`display-options` - Customize the visual appearance including colors and labels +* :ref:`output-control` - Select output formats and set the destination directory +* :ref:`project-configuration` - Define project settings like source roots and ignored files +""" + ] options: list[OptionsData] = [OptionsData(name, info) for name, info in run.options] option_groups: dict[str, list[str]] = {g: [] for g in OPTIONS_GROUPS.values()} for option in sorted(options, key=lambda x: x.name): - option_string = get_rst_title(f"--{option.name}", '"') + option_string = get_rst_title(f"--{option.name}", "-") option_string += f"*{option.optdict.get('help')}*\n\n" if option.optdict.get("default") == "": @@ -50,8 +66,14 @@ def _write_config_page(run: Run) -> None: option_groups[str(option.optdict.get("group"))].append(option_string) for group_title in OPTIONS_GROUPS.values(): + ref_title = group_title.lower().replace(" ", "-") sections.append( - get_rst_title(group_title, "-") + "\n" + "".join(option_groups[group_title]) + f"""\ +.. _{ref_title}: + +{get_rst_title(group_title, "=")} + +{"".join(option_groups[group_title])}""" ) # Join all sections and remove the final two newlines diff --git a/doc/index.rst b/doc/index.rst index 8bcdeac8bb..d1e862987b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -30,6 +30,7 @@ .. toctree:: :caption: Additional tools + :maxdepth: 3 :titlesonly: :hidden: