Add detailed documentation for Pyreverse command-line options

[Julfried]

Type of Changes

	Type
	🐛 Bug fix
	✨ New feature
	🔨 Refactoring
✓	📜 Docs

Description

Add detailed documentation for all Pyreverse command-line options, organized into logical sections:

• Output Control (format, directory, project settings)
• Filtering and Scope (filter modes, class focus, ancestors)
• Display Options (module names, colorization)
• Project Configuration (ignore patterns, source roots)

Closes #9573

[codecov]

Codecov Report

Attention: Patch coverage is 77.77778% with 2 lines in your changes missing coverage. Please review.

Project coverage is 95.79%. Comparing base (2e0c41f) to head (c4cc8a5).
Report is 72 commits behind head on main.

Files with missing lines	Patch %	Lines
pylint/pyreverse/main.py	71.42%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #10045      +/-   ##
==========================================
- Coverage   95.80%   95.79%   -0.02%     
==========================================
  Files         174      174              
  Lines       18937    18937              
==========================================
- Hits        18143    18141       -2     
- Misses        794      796       +2     

Files with missing lines	Coverage Δ
pylint/__init__.py	94.11% <100.00%> (ø)
pylint/pyreverse/inspector.py	79.89% <100.00%> (ø)
pylint/pyreverse/main.py	91.66% <71.42%> (-2.09%)	⬇️

... and 2 files with indirect coverage changes

[Pierre-Sassoulas]

Thank you for your work on this. I feel like it should be based on the output of argparse so it's up to date automatically when we modify pyreverse input but it should be stable enough. Waiting for the pyreverse's experts opinion :D

[DanielNoord]

Could you add this documentation to the options like so:

pylint/pylint/pyreverse/main.py

Line 244 in 3fca43a

"help": "set the output directory path.",

It would be a waste to not save the effort you made to write these.

We can then look into rendering these help texts correctly.

We probably need a doc extension very similar to:
https://github.com/pylint-dev/pylint/blob/3fca43aa15047ff62f775c27d0c3e85aaa935549/doc/exts/pylint_options.py

[Julfried]

Thanks for the feedback. I agree, that it feels right to automate this for the future and maintaining the documenation texts directly in the code is a lot better for consistency. I will add my docs to the options, like you mentioned. Regarding the automation part I will have to look into this, but it feels like a bigger change, so I am not sure if I find the time for this right now :D

[DudeNr33]

I really like the grouped output, it is also a great benefit for the help output on the command line. Thanks!
Fully agree that automatically generating it would be ideal for the future, but personally I would be fine to put this in a follow-up PR.

One minor thing I noticed when running it locally: The docstring of the Run class is included below every option group, e.g.:

Filtering and Scope:
  Base class providing common behaviour for pyreverse commands.

  --filter-mode <mode>, -f <mode>

From a first glance I would say that is a side-effect from ArgumentsManager._register_options_provider being tailored towards the use cases of Pylint checker classes .

As the Run class is fairly short and the docstring very generic, I am in favor of simply removing it.

[Julfried]

Thanks for the feedback. I think turning the docstring into a regular python comment to preserve documentation would be a good idea.

[DanielNoord]

Fighting with CI and tests but wrote a quick little docs extension that renders your awesome documentation as a page:
https://pylint--10045.org.readthedocs.build/en/10045/additional_tools/pyreverse/configuration.html

I'll make sure CI is green and then you can take over again in case you want to tweak how stuff looks.
You can test this locally by going into doc, running make html and opening doc/_build/html/index.html in your browser.

[Julfried]

Awesome, thank you! Will look into it👍

[DanielNoord]

Since I also changed the API for pyreverse: @DudeNr33 mind giving this a look?

@Pierre-Sassoulas rest of the PR can probably be reviewed by you? Unless @Julfried wants to make many changes to the documentation I would probably review this and do any follow up to the documentation itself in a subsequent PR that is fixed on the documentation. This is already doing quite a bit 😅

[github-actions]

🤖 According to the primer, this change has no effect on the checked open source code. 🤖🎉

This comment was generated for commit c4cc8a5

[Pierre-Sassoulas]

Wow this sphinx plugin and the generated result looks amazing. Right now it's hard to see the new page because the main page have no link to it. So I would just reorganize the pyreverse doc a little accommodate the newly created page. Probably a main page with a lot less text and two links, one to the new page, and one to a new subpage with most of the current main page's text. What do you think ?

[DanielNoord]

Wow this sphinx plugin and the generated result looks amazing. Right now it's hard to see the new page because the main page have no link to it. So I would just reorganize the pyreverse doc a little accommodate the newly created page. Probably a main page with a lot less text and two links, one to the new page, and one to a new subpage with most of the current main page's text. What do you think ?

Do you mind if we do that in a follow up? This is already a pretty big PR as it is. With the new framework it would be fairly trivial to move around pages and do some better formatting everywhere

[DanielNoord]

@Julfried Let me know if there is anything you want to change in this PR. If not, I will merge this!

[Julfried]

I think the description of the pyreverse options looks very good to me and I would leave it as it is. I agree that the pages for pyreverse should be better structured, however this is better for a follow up👍

[DanielNoord]

Merged!

@Julfried Are you up for making those last improvements?