Improve pyreverse documentation

doc/additional_tools/pyreverse/configuration.rst

@@ -2,37 +2,54 @@
 .. docs extension in 'doc/exts/pyreverse_configuration.py'.
 
 
+Basic usage
+###########
 
-Pyreverse Configuration
-^^^^^^^^^^^^^^^^^^^^^^^
+
+To run ``pyreverse``, use::
+
+  pyreverse [options] <packages>
+
+
+``<packages>`` 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 <filtering-and-scope>` - Options for filtering classes and limiting the scope of the generated diagrams.
+* :ref:`Display Options <display-options>` - Customize how diagrams are rendered, including colors and module names.
+* :ref:`Output Control <output-control>` - Specify output formats and directory locations for generated files.
+* :ref:`Project Configuration <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 <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,28 +60,28 @@ 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``
@@ -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 <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``
@@ -120,17 +140,20 @@ Display Options
 
 
 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:** ``""``
@@ -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``

doc/additional_tools/pyreverse/index.rst

@@ -1,7 +1,8 @@
 .. _pyreverse:
 
+=========
 Pyreverse
----------
+=========
 
 ``pyreverse`` analyzes your source code and generates package and class diagrams.
 
@@ -10,63 +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.
 
-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
-
 .. toctree::
   :maxdepth: 1
-  :hidden:
 
   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

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", "^"),
-    ]
+        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] <packages>
+
 
+``<packages>`` 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 <filtering-and-scope>` - Options for filtering classes and limiting the scope of the generated diagrams.
+* :ref:`Display Options <display-options>` - Customize how diagrams are rendered, including colors and module names.
+* :ref:`Output Control <output-control>` - Specify output formats and directory locations for generated files.
+* :ref:`Project Configuration <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