Make reference check catch stale manual signatures

[DevilsAutumn]

What happened?

docs:reference:check passes manual reference pages as long as every public symbol anchor is present. It does not check if the shown signature or parameter table still matches the real public API.

So a manual page can keep the right anchor but show an old signature, and CI will still pass.

Expected behavior

The reference check should fail when manual reference docs have stale public signatures, defaults, or parameter tables for documented symbols.

Reproduction

Please share a small code example, command, or test case if possible.

from pathlib import Path
import tempfile
import scripts.generate_reference as gen

# Create manual reference pages with the right symbol anchors but wrong signature text.
# gen.read_manual_reference(...) still returns outputs today because it only checks anchors.

Environment

• Quater version: current main
• Python version: 3.11
• OS: macOS

Extra context

Issue #131 is about tests for signature formatting helpers. This one is different. This should test the actual reference check behavior for manual docs, so stale docs do not pass only because the anchor is still there.

Working on this?

Please wait until a maintainer marks the issue accepted. After that, comment before starting and make sure nobody else is assigned or already working on it.

[kashvipeehu24]

Hi! I'd like to work on this issue. Could you please assign it to me?

[kashvipeehu24]

Hello sir ! I've started looking into this issue. I found that read_manual_reference() currently validates the presence of anchors, but not whether the documented signatures match the current public API. Before I proceed, could you point me to the preferred way to obtain the expected signature for comparison? I found class_signature() and method_signature(), but I'm not yet sure how you'd like this validation integrated. I just want to make sure I follow the project's intended design.

…

On Fri, 26 Jun, 2026, 6:31 am Bhuvnesh, ***@***.***> wrote: Assigned #141 <#141> to @kashvipeehu24 <https://github.com/kashvipeehu24>. — Reply to this email directly, view it on GitHub <#141?email_source=notifications&email_token=BYEG45REN4YX2C45DP55IDD5BXDNHA5CNFSNUABQM5UWIORPF5TWS5BNNB2WEL2JONZXKZKFOZSW45CON52GSZTJMNQXI2LPNYXTENZSGI3DINRXG42THJTSMVQXG33OUZQXG43JM5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#event-27226467753>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BYEG45TA6IW67T2RBMZMAYL5BXDNHAVCNFSNUABGKJSXA33TNF2G64TZHMYTEMZSGA3TGMZQGI5US43TOVSTWNBXGAYTQMJTGQ3TFILWAI> . You are receiving this because you were assigned.Message ID: ***@***.***>

[DevilsAutumn]

Hey @kashvipeehu24 , thanks for checking this out.

Yes, you’re looking in the right place. Please use the existing helpers in scripts/generate_reference.py. The expected signature should come from the package object we already load with Griffe.

The fix should be in the manual docs check. Right now it only checks that the anchor is there. It should also fail if the signature or parameter table in the docs is old.

A good test that can be added: keep the right anchor, change the signature in the docs to an old one, and make sure docs:reference:check fails.

[kashvipeehu24]

Hello sir ! I tried implementing the manual docs freshness check using the existing helpers in generate_reference.py as you suggested. I can see how the anchor check works, but I'm still unsure which helper should be used to generate the expected signature/parameter table for comparison against the manual docs. Could you point me to the specific helper or function that should be reused here? I want to make sure I implement it the way the project intends.

…

On Fri, 26 Jun, 2026, 5:50 pm Bhuvnesh, ***@***.***> wrote: *DevilsAutumn* left a comment (DevilsAutumn/quater#141) <#141 (comment)> Hey @kashvipeehu24 <https://github.com/kashvipeehu24> , thanks for checking this out. Yes, you’re looking in the right place. Please use the existing helpers in scripts/generate_reference.py. The expected signature should come from the package object we already load with Griffe. The fix should be in the manual docs check. Right now it only checks that the anchor is there. It should also fail if the signature or parameter table in the docs is old. A good test that can be added: keep the right anchor, change the signature in the docs to an old one, and make sure docs:reference:check fails. — Reply to this email directly, view it on GitHub <#141?email_source=notifications&email_token=BYEG45WJ6MKRE4NU47VR7735BZTB7A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOBQHE2TCMJVGA42M4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-4809511509>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BYEG45XJG2MCWRJ3CSTXYCT5BZTB7AVCNFSNUABGKJSXA33TNF2G64TZHMYTEMZSGA3TGMZQGI5US43TOVSTWNBXGAYTQMJTGQ3TFILWAI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[DevilsAutumn]

Hi @kashvipeehu24,

For signatures, please reuse these helpers:

• class_signature(package, symbol) for class constructors like Quater
• method_signature(package, symbol, method) for methods like Quater.route
• callable_signature(package, symbol) for callable symbols like Path, Query, etc.

For parameter tables, use:

• parameter_table(package, symbol, method)
• function_parameter_table(package, symbol)

You can also look at validated_option_table() and validated_function_option_table() for the current pattern.

The change should go in read_manual_reference(). Right now it only checks that the symbol anchor exists. It should also check that the manual page has the current signature and parameter table.

[DevilsAutumn]

@kashvipeehu24 Any updates on this one?

[kashvipeehu24]

So sorry for the delay. I would be finishing this today before evening.

…

On Thu, 9 Jul, 2026, 10:09 am Bhuvnesh, ***@***.***> wrote: *DevilsAutumn* left a comment (DevilsAutumn/quater#141) <#141 (comment)> @kashvipeehu24 <https://github.com/kashvipeehu24> Any updates on this one? — Reply to this email directly, view it on GitHub <#141?email_source=notifications&email_token=BYEG45S7E74ETVCNZHFGGO35D4OW5A5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIOJSGE3DCOBVGIZKM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-4921618522>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BYEG45XCX5NPZCM733GULRD5D4OW5AVCNFSNUABGKJSXA33TNF2G64TZHMYTEMZSGA3TGMZQGI5US43TOVSTWNBXGAYTQMJTGQ3TFILWAI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[kashvipeehu24]

Hi! I wanted to give you a quick update. I investigated the documentation generator and traced the remaining issue to the AppConfig signature validation in generate_reference.py. The generator still reports a stale signature for the manual reference page, and I'm currently comparing the generated signature with the manual documentation to determine whether the normalization logic or the documentation needs updating. I appreciate your patience and expect to have a concrete fix as soon as I've resolved that mismatch.