Fix caching issue that led to incorrect all-options.rst being merged on main

[Julfried]

Type of Changes

	Type
✓	📜 Docs

Description

Somehow #10314 did not change the .rst file in docs, which messed up pre-commit ci for me

[correctmost]

The top of the file says it is auto-generated, so I thought it would get updated as part of the release process. I didn't encounter any pre-commit failures locally when preparing that PR, so maybe my environment is different somehow?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.89%. Comparing base (4471242) to head (dc4dfe8).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #10320   +/-   ##
=======================================
  Coverage   95.89%   95.89%           
=======================================
  Files         175      175           
  Lines       19084    19084           
=======================================
  Hits        18301    18301           
  Misses        783      783           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Julfried]

As far as I understand the .rst files are generated when running make html before you push. If you have pre-commit hooks installed this should be executed automatically when pushing. Maybe it is also an error with my environment, since ci fails here aswell :)

[Pierre-Sassoulas]

pre-commit is not regenerating all the doc all the time (tox -e docs / make html is very slow), but I think we check in the CI now (we were simply regenerating before a release before).

[Pierre-Sassoulas]

If there's a mistake in all-options it means the mistake is elsewhere too as this file is generated.

[Julfried]

Maybe I need to clarify. I think what happened is that in #10314 the description in typecheck.py was changed from minimum to maximum, however make html was never executed, which left all-options.rst unchanged. So when I wanted to push something in my fork, running the pre-commit hooks complained that executing make html produced a diff for me and preventing me to push

[Pierre-Sassoulas]

What is strange is that the CI runs a check in Checks/ Documentation (and also runs pre-commit) so, we have the branch for #10314 passing test, we merge it then main fail, and then fixing it here fail the check again (while supposedly working for you locally). Do you mind resetting your local installation to make sure the version of pylint used to generate the doc is the right one ?

[Julfried]

I pulled the main branch on a different machine with a fresh environment. Running make html still produces this diff for me:

diff --git a/doc/user_guide/configuration/all-options.rst b/doc/user_guide/configuration/all-options.rst
index 7a9cec81a..82ade5b52 100644
--- a/doc/user_guide/configuration/all-options.rst
+++ b/doc/user_guide/configuration/all-options.rst
@@ -1501,7 +1501,7 @@ Standard Checkers

 --missing-member-hint-distance
 """"""""""""""""""""""""""""""
-*The minimum edit distance a name should have in order to be considered a similar match for a missing member name.*
+*The maximum edit distance a name should have in order to be considered a similar match for a missing member name.*
:

[Pierre-Sassoulas]

I can reproduce the issue locally (a diff on main, no diff on this branch when regenerating the doc). We'll end up merging it but I have no idea what is going wrong in CI atm.

[Julfried]

I was wondering if this is a caching issue with pre-commit? Because, when looking at the logs for the first run when I opened this PR, it somehow wanted to revert my changes based on the git diff that is produced. However this can not be from the right source code because typecheck.py was updated in my branch, so maybe pre-commit has cached older files and running pre-commit run --hook-stage push sphinx-generated-doc --all-files in CI uses that?

logs:

2025-03-29T09:57:00.0543760Z git diff:
2025-03-29T09:57:00.0544058Z diff --git a/doc/user_guide/configuration/all-options.rst b/doc/user_guide/configuration/all-options.rst
2025-03-29T09:57:00.0544146Z index 82ade5b..7a9cec8 100644
2025-03-29T09:57:00.0544264Z --- a/doc/user_guide/configuration/all-options.rst
2025-03-29T09:57:00.0544378Z +++ b/doc/user_guide/configuration/all-options.rst
2025-03-29T09:57:00.0544584Z @@ -1501,7 +1501,7 @@ Standard Checkers
2025-03-29T09:57:00.0544650Z  
2025-03-29T09:57:00.0544748Z  --missing-member-hint-distance
2025-03-29T09:57:00.0544816Z  """"""""""""""""""""""""""""""
2025-03-29T09:57:00.0545108Z -*The maximum edit distance a name should have in order to be considered a similar match for a missing member name.*
2025-03-29T09:57:00.0545384Z +*The minimum edit distance a name should have in order to be considered a similar match for a missing member name.*
2025-03-29T09:57:00.0545447Z  
2025-03-29T09:57:00.0545516Z  **Default:**  ``1``
2025-03-29T09:57:00.0545580Z  
2025-03-29T09:57:00.0545647Z End of 'git diff'

[Julfried]

This would also explain why the check is passing now when using tox. What do you think?

[Pierre-Sassoulas]

I agree it must be a caching issue but it's probably not from pre-commit but from our 'check documentation' github action caching.

[Julfried]

What do you think of replacing setup-python with uv in this job? In my experience lately, uv without cache is as fast as setup-python + cache, but we would avoid having to deal with these caching side effects

[Pierre-Sassoulas]

Sounds good (tox is slower than make because it create the whole env before launching make, bypassing the cache)

[Julfried]

Alright, should we do it here or in a follow up?

[Pierre-Sassoulas]

I'm wondering if caching the result of an editable install is a problem. Maybe we need to install the current pylint outside of the cached mechanism. (The problem also appeared in the test here: https://github.com/pylint-dev/pylint/actions/runs/14155616302/job/39654454133?pr=9962)

[Pierre-Sassoulas]

Doing it here is fine, I see this PR as "fixing the cache and the generated doc that was broken by the cache issue"

[DanielNoord]

Locally without this commit pre-commit run --hook-stage push sphinx-generated-doc --all-files also doesn't create a git diff for me.

I think we just shouldn't use pre-commit here.

[Pierre-Sassoulas]

Locally without this commit pre-commit run --hook-stage push sphinx-generated-doc --all-files also doesn't create a git diff for me.

Personally, on the contrary I have a diff on main or branch rebased on main and I don't have a diff on this branch. Not sure about the reason for the discrepancy here.

I think we just shouldn't use pre-commit here.

We can remove the pre-commit though as probably no one install it and it's very slow on every push even unrelated to doc chances it's a nightmate. (I use tox -e docs only on doc change personally, but there's 3 ways to do it right now, which is bad)

[DanielNoord]

Are we sure this is correct? Wouldn't this always exit 1?

[Pierre-Sassoulas]

If tox -e docs is true this exit with 0

Took over this MR, not in a position to review anymore.

[Pierre-Sassoulas]

@Julfried the uv refactor is still welcome but let's do it in a follow-up MR, using tox is not efficient but it's a fast fix that could be permanent and it will unblock the other PR.

[Julfried]

@Pierre-Sassoulas thank you, will do it :)

[github-actions]

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

This comment was generated for commit dc4dfe8