Improve pyreverse documentation (#10063)

Co-authored-by: Pierre Sassoulas <pierre.sassoulas@gmail.com>

Author: Julfried

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] <packages>
+
+where ``<packages>`` 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 <projects>.*
 
 **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 <class>; this uses by default the options -ASmy*
 
 **Default:**  ``None``
 
 
 --filter-mode
-"""""""""""""
+-------------
 *Filter attributes and functions according to <mode>. Correct modes are:
 'PUB_ONLY' filter all non public attributes [DEFAULT], equivalent to PRIVATE+SPECIAL
 'ALL' no filter
@@ -43,127 +59,136 @@ Filtering and Scope
 
 
 --show-ancestors
-""""""""""""""""
+----------------
 *Show <ancestor> generations of ancestor classes not in <projects>.*
 
 **Default:**  ``None``
 
 
 --show-associated
-"""""""""""""""""
+-----------------
 *Show <association_level> levels of associated classes not in <projects>.*
 
 **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``
 
 
 
 
+.. _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 <depth>. 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``
 
 
 
 
+.. _output-control:
+
 Output Control
---------------
+==============
+
 
 --output
-""""""""
+--------
 *Create a *.<format> 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 <https://graphviz.org/docs/outputs/>`_).*
 
 **Default:**  ``dot``
 
 
 --output-directory
-""""""""""""""""""
+------------------
 *Set the output directory path.*
 
 **Default:** ``""``
 
 
 
 
+.. _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``

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 <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.
+- 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] <packages>
+* Native formats:
+    * ``.dot``/``.gv`` (Graphviz)
+    * ``.puml``/``.plantuml`` (PlantUML)
+    * ``.mmd``/``.html`` (MermaidJS)
 
-<packages> 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 <https://graphviz.org/docs/outputs/>`_ (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

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