From 49be51e9c361fabe41e742132d2b13f58ade98de Mon Sep 17 00:00:00 2001 From: Julfried <51880314+Julfried@users.noreply.github.com> Date: Sun, 3 Nov 2024 14:05:06 +0100 Subject: [PATCH 1/6] restructure pyreverse documentation --- .../pyreverse/configuration.rst | 4 ++-- doc/additional_tools/pyreverse/index.rst | 22 ++++++++++++++++--- doc/exts/pyreverse_configuration.py | 2 +- 3 files changed, 22 insertions(+), 6 deletions(-) diff --git a/doc/additional_tools/pyreverse/configuration.rst b/doc/additional_tools/pyreverse/configuration.rst index aa42e8c9a5..4588ddecbd 100644 --- a/doc/additional_tools/pyreverse/configuration.rst +++ b/doc/additional_tools/pyreverse/configuration.rst @@ -3,8 +3,8 @@ -Pyreverse Configuration -^^^^^^^^^^^^^^^^^^^^^^^ +Pyreverse Configuration Options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Filtering and Scope diff --git a/doc/additional_tools/pyreverse/index.rst b/doc/additional_tools/pyreverse/index.rst index 41f74731dc..1689555a2d 100644 --- a/doc/additional_tools/pyreverse/index.rst +++ b/doc/additional_tools/pyreverse/index.rst @@ -10,18 +10,34 @@ If Graphviz (or the ``dot`` command) is installed, all `output formats supported 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 +Using Pyreverse ''''''''''''''''' To run ``pyreverse``, use:: pyreverse [options] - can also be a single Python module. -To see a full list of the available options, run:: +[options] can be specified to modify the behavior of pyreverse, and + can either be a package or a list of modules separated by spaces. + +Configuration Options +..................... + +To see a full list of the available [options], run:: pyreverse -h +For detailed descriptions of the command-line options available for Pyreverse, refer to the dedicated `Pyreverse Configuration Options `_ page. This page includes sections on: + +* `Filtering and Scope `_ - Options for filtering classes and limiting the scope of the generated diagrams. +* `Display Options `_ - Customize how diagrams are rendered, including colors and module names. +* `Output Control `_ - Specify output formats and directory locations for generated files. +* `Project Configuration `_ - Configure project-specific settings such as ignored files and source roots. + +.. toctree:: + :maxdepth: 1 + :hidden: + Example Output '''''''''''''' diff --git a/doc/exts/pyreverse_configuration.py b/doc/exts/pyreverse_configuration.py index f4d77ef216..f419c81513 100644 --- a/doc/exts/pyreverse_configuration.py +++ b/doc/exts/pyreverse_configuration.py @@ -32,7 +32,7 @@ def _write_config_page(run: Run) -> None: 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", "^"), + get_rst_title("Pyreverse Configuration Options", "^"), ] options: list[OptionsData] = [OptionsData(name, info) for name, info in run.options] From 124e72d85bf1c116661afe591683052a6d88d53f Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Sun, 3 Nov 2024 22:10:06 +0100 Subject: [PATCH 2/6] [doc pyreverse] Add a level for creating a class diagram --- .../pyreverse/create_class_diagram.rst | 17 ++++++++++++++++ doc/additional_tools/pyreverse/index.rst | 20 +------------------ 2 files changed, 18 insertions(+), 19 deletions(-) create mode 100644 doc/additional_tools/pyreverse/create_class_diagram.rst diff --git a/doc/additional_tools/pyreverse/create_class_diagram.rst b/doc/additional_tools/pyreverse/create_class_diagram.rst new file mode 100644 index 0000000000..92a84210ef --- /dev/null +++ b/doc/additional_tools/pyreverse/create_class_diagram.rst @@ -0,0 +1,17 @@ +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/additional_tools/pyreverse/index.rst b/doc/additional_tools/pyreverse/index.rst index 1689555a2d..a305576162 100644 --- a/doc/additional_tools/pyreverse/index.rst +++ b/doc/additional_tools/pyreverse/index.rst @@ -62,27 +62,9 @@ Package Diagram :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 - .. toctree:: :maxdepth: 1 :hidden: configuration + create_class_diagram From 52a263aaa5b2992832f7b2fbb2db5393ce145ed0 Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Mon, 4 Nov 2024 22:28:54 +0100 Subject: [PATCH 3/6] [doc] Reoganization/clarification of the pyreverse doc --- .../pyreverse/configuration.rst | 78 ++++++++++++------- doc/additional_tools/pyreverse/index.rst | 58 +------------- ..._class_diagram.rst => output_examples.rst} | 23 ++++++ doc/exts/pyreverse_configuration.py | 34 ++++++-- 4 files changed, 106 insertions(+), 87 deletions(-) rename doc/additional_tools/pyreverse/{create_class_diagram.rst => output_examples.rst} (63%) diff --git a/doc/additional_tools/pyreverse/configuration.rst b/doc/additional_tools/pyreverse/configuration.rst index 4588ddecbd..712265a489 100644 --- a/doc/additional_tools/pyreverse/configuration.rst +++ b/doc/additional_tools/pyreverse/configuration.rst @@ -2,37 +2,54 @@ .. docs extension in 'doc/exts/pyreverse_configuration.py'. +Basic usage +########### -Pyreverse Configuration Options -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To run ``pyreverse``, use:: + + pyreverse [options] + + +```` can either be a package or a list of modules separated by spaces. + +For detailed descriptions of the command-line options read on. This page includes sections on: + +* :ref:`Filtering and Scope ` - Options for filtering classes and limiting the scope of the generated diagrams. +* :ref:`Display Options ` - Customize how diagrams are rendered, including colors and module names. +* :ref:`Output Control ` - Specify output formats and directory locations for generated files. +* :ref:`Project Configuration ` - Configure project-specific settings such as ignored files and source roots. 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 +60,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`` @@ -73,45 +90,48 @@ 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`` @@ -120,17 +140,20 @@ 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:** ``""`` @@ -139,31 +162,34 @@ 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 a305576162..8f6b21f6c2 100644 --- a/doc/additional_tools/pyreverse/index.rst +++ b/doc/additional_tools/pyreverse/index.rst @@ -1,7 +1,8 @@ .. _pyreverse: +========= Pyreverse ---------- +========= ``pyreverse`` analyzes your source code and generates package and class diagrams. @@ -10,61 +11,8 @@ If Graphviz (or the ``dot`` command) is installed, all `output formats supported 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. -Using Pyreverse -''''''''''''''''' - -To run ``pyreverse``, use:: - - pyreverse [options] - -[options] can be specified to modify the behavior of pyreverse, and - can either be a package or a list of modules separated by spaces. - -Configuration Options -..................... - -To see a full list of the available [options], run:: - - pyreverse -h - -For detailed descriptions of the command-line options available for Pyreverse, refer to the dedicated `Pyreverse Configuration Options `_ page. This page includes sections on: - -* `Filtering and Scope `_ - Options for filtering classes and limiting the scope of the generated diagrams. -* `Display Options `_ - Customize how diagrams are rendered, including colors and module names. -* `Output Control `_ - Specify output formats and directory locations for generated files. -* `Project Configuration `_ - Configure project-specific settings such as ignored files and source roots. - -.. toctree:: - :maxdepth: 1 - :hidden: - -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 - .. toctree:: :maxdepth: 1 - :hidden: configuration - create_class_diagram + output_examples diff --git a/doc/additional_tools/pyreverse/create_class_diagram.rst b/doc/additional_tools/pyreverse/output_examples.rst similarity index 63% rename from doc/additional_tools/pyreverse/create_class_diagram.rst rename to doc/additional_tools/pyreverse/output_examples.rst index 92a84210ef..32fdfc8f07 100644 --- a/doc/additional_tools/pyreverse/create_class_diagram.rst +++ b/doc/additional_tools/pyreverse/output_examples.rst @@ -1,3 +1,26 @@ +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 '''''''''''''''''''''''''''''''''''''''''''' diff --git a/doc/exts/pyreverse_configuration.py b/doc/exts/pyreverse_configuration.py index f419c81513..0acaa946d4 100644 --- a/doc/exts/pyreverse_configuration.py +++ b/doc/exts/pyreverse_configuration.py @@ -30,16 +30,33 @@ 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 Options", "^"), - ] + f"""\ +.. This file is auto-generated. Make any changes to the associated +.. docs extension in 'doc/exts/pyreverse_configuration.py'. + + +{get_rst_title("Basic usage", "#")} + +To run ``pyreverse``, use:: + + pyreverse [options] + +```` can either be a package or a list of modules separated by spaces. + +For detailed descriptions of the command-line options read on. This page includes sections on: + +* :ref:`Filtering and Scope ` - Options for filtering classes and limiting the scope of the generated diagrams. +* :ref:`Display Options ` - Customize how diagrams are rendered, including colors and module names. +* :ref:`Output Control ` - Specify output formats and directory locations for generated files. +* :ref:`Project Configuration ` - Configure project-specific settings such as ignored files and source roots. +""" # noqa: E501 + ] 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 +67,13 @@ 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"""{get_rst_title(group_title, "#")} +.. _{ref_title}: + + +{"".join(option_groups[group_title])}""" ) # Join all sections and remove the final two newlines From 18ee1c3d721790051a257f7d0afac17956561cfb Mon Sep 17 00:00:00 2001 From: Pierre Sassoulas Date: Sun, 10 Nov 2024 09:27:56 +0100 Subject: [PATCH 4/6] work in progress more depth --- doc/additional_tools/pyreverse/configuration.rst | 12 ++++++------ doc/additional_tools/pyreverse/index.rst | 5 ++++- doc/exts/pyreverse_configuration.py | 4 ++-- doc/index.rst | 1 + 4 files changed, 13 insertions(+), 9 deletions(-) diff --git a/doc/additional_tools/pyreverse/configuration.rst b/doc/additional_tools/pyreverse/configuration.rst index 712265a489..010e2757f7 100644 --- a/doc/additional_tools/pyreverse/configuration.rst +++ b/doc/additional_tools/pyreverse/configuration.rst @@ -2,8 +2,8 @@ .. docs extension in 'doc/exts/pyreverse_configuration.py'. -Basic usage -########### +Usage +##### To run ``pyreverse``, use:: @@ -22,7 +22,7 @@ For detailed descriptions of the command-line options read on. This page include Filtering and Scope -################### +''''''''''''''''''' .. _filtering-and-scope: @@ -90,7 +90,7 @@ Filtering and Scope Display Options -############### +''''''''''''''' .. _display-options: @@ -140,7 +140,7 @@ Display Options Output Control -############## +'''''''''''''' .. _output-control: @@ -162,7 +162,7 @@ Output Control Project Configuration -##################### +''''''''''''''''''''' .. _project-configuration: diff --git a/doc/additional_tools/pyreverse/index.rst b/doc/additional_tools/pyreverse/index.rst index 8f6b21f6c2..5911c0451a 100644 --- a/doc/additional_tools/pyreverse/index.rst +++ b/doc/additional_tools/pyreverse/index.rst @@ -12,7 +12,10 @@ can be used as well. In this case, ``pyreverse`` first generates a temporary ``. fed to Graphviz to generate the final image. .. toctree:: - :maxdepth: 1 + :caption: Pyreverse + :maxdepth: 3 + :titlesonly: + :hidden: configuration output_examples diff --git a/doc/exts/pyreverse_configuration.py b/doc/exts/pyreverse_configuration.py index 0acaa946d4..48e8f8a9b3 100644 --- a/doc/exts/pyreverse_configuration.py +++ b/doc/exts/pyreverse_configuration.py @@ -35,7 +35,7 @@ def _write_config_page(run: Run) -> None: .. docs extension in 'doc/exts/pyreverse_configuration.py'. -{get_rst_title("Basic usage", "#")} +{get_rst_title("Usage", "#")} To run ``pyreverse``, use:: @@ -69,7 +69,7 @@ def _write_config_page(run: Run) -> None: for group_title in OPTIONS_GROUPS.values(): ref_title = group_title.lower().replace(" ", "-") sections.append( - f"""{get_rst_title(group_title, "#")} + f"""{get_rst_title(group_title, "'")} .. _{ref_title}: 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: From 7ea4d4505b3cff69ae8db4dfe184b851e00da268 Mon Sep 17 00:00:00 2001 From: Julfried <51880314+Julfried@users.noreply.github.com> Date: Sun, 10 Nov 2024 11:38:10 +0100 Subject: [PATCH 5/6] different solution for depth issue --- .../pyreverse/configuration.rst | 77 +++++++++---------- doc/additional_tools/pyreverse/index.rst | 12 +-- doc/exts/pyreverse_configuration.py | 22 +++--- 3 files changed, 55 insertions(+), 56 deletions(-) diff --git a/doc/additional_tools/pyreverse/configuration.rst b/doc/additional_tools/pyreverse/configuration.rst index 010e2757f7..845386e533 100644 --- a/doc/additional_tools/pyreverse/configuration.rst +++ b/doc/additional_tools/pyreverse/configuration.rst @@ -6,50 +6,49 @@ Usage ##### -To run ``pyreverse``, use:: +``pyreverse`` is run from the command line using the following syntax:: pyreverse [options] +where ```` is one or more Python packages or modules to analyze. -```` can either be a package or a list of modules separated by spaces. +The available options are organized into the following categories: -For detailed descriptions of the command-line options read on. This page includes sections on: +* :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 -* :ref:`Filtering and Scope ` - Options for filtering classes and limiting the scope of the generated diagrams. -* :ref:`Display Options ` - Customize how diagrams are rendered, including colors and module names. -* :ref:`Output Control ` - Specify output formats and directory locations for generated files. -* :ref:`Project Configuration ` - Configure project-specific settings such as ignored files and source roots. +.. _filtering-and-scope: 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 @@ -60,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`` @@ -89,49 +88,49 @@ Filtering and Scope -Display Options -''''''''''''''' - .. _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`` @@ -139,21 +138,21 @@ Display Options -Output Control -'''''''''''''' - .. _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:** ``""`` @@ -161,35 +160,35 @@ Output Control -Project Configuration -''''''''''''''''''''' - .. _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 5911c0451a..f2b0d58ae5 100644 --- a/doc/additional_tools/pyreverse/index.rst +++ b/doc/additional_tools/pyreverse/index.rst @@ -12,10 +12,10 @@ can be used as well. In this case, ``pyreverse`` first generates a temporary ``. fed to Graphviz to generate the final image. .. toctree:: - :caption: Pyreverse - :maxdepth: 3 - :titlesonly: - :hidden: + :maxdepth: 2 + :caption: Pyreverse + :titlesonly: + :hidden: - configuration - output_examples + configuration + output_examples diff --git a/doc/exts/pyreverse_configuration.py b/doc/exts/pyreverse_configuration.py index 48e8f8a9b3..f4dde54357 100644 --- a/doc/exts/pyreverse_configuration.py +++ b/doc/exts/pyreverse_configuration.py @@ -37,26 +37,25 @@ def _write_config_page(run: Run) -> None: {get_rst_title("Usage", "#")} -To run ``pyreverse``, use:: +``pyreverse`` is run from the command line using the following syntax:: pyreverse [options] +where ```` is one or more Python packages or modules to analyze. -```` can either be a package or a list of modules separated by spaces. +The available options are organized into the following categories: -For detailed descriptions of the command-line options read on. This page includes sections on: - -* :ref:`Filtering and Scope ` - Options for filtering classes and limiting the scope of the generated diagrams. -* :ref:`Display Options ` - Customize how diagrams are rendered, including colors and module names. -* :ref:`Output Control ` - Specify output formats and directory locations for generated files. -* :ref:`Project Configuration ` - Configure project-specific settings such as ignored files and source roots. -""" # noqa: E501 +* :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") == "": @@ -69,9 +68,10 @@ def _write_config_page(run: Run) -> None: for group_title in OPTIONS_GROUPS.values(): ref_title = group_title.lower().replace(" ", "-") sections.append( - f"""{get_rst_title(group_title, "'")} + f"""\ .. _{ref_title}: +{get_rst_title(group_title, "=")} {"".join(option_groups[group_title])}""" ) From 9891da491b80c5c9b38d5608764a1801a2e05074 Mon Sep 17 00:00:00 2001 From: Julfried <51880314+Julfried@users.noreply.github.com> Date: Sun, 10 Nov 2024 17:27:20 +0100 Subject: [PATCH 6/6] also beautify pyreverse main page --- doc/additional_tools/pyreverse/index.rst | 29 ++++++++++++++++++++---- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/doc/additional_tools/pyreverse/index.rst b/doc/additional_tools/pyreverse/index.rst index f2b0d58ae5..4dc8a9b4b1 100644 --- a/doc/additional_tools/pyreverse/index.rst +++ b/doc/additional_tools/pyreverse/index.rst @@ -4,12 +4,31 @@ 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 + +Output Formats +============== + +``pyreverse`` supports multiple output formats: + +* Native formats: + * ``.dot``/``.gv`` (Graphviz) + * ``.puml``/``.plantuml`` (PlantUML) + * ``.mmd``/``.html`` (MermaidJS) + +* 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 + +Getting Started +=============== + +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: 2