Fixed #170 -- Split generate_reference.py into focused internal modules by utk2103 · Pull Request #180 · DevilsAutumn/quater

utk2103 · 2026-07-15T09:48:31Z

Summary

Split 2462-line scripts/generate_reference.py into scripts/_reference/ package: paths, pages, manual, signatures, types, tables,
render, output.
Entry scripts/generate_reference.py reduced to a thin CLI (66 lines) that re-exports format_signature, split_top_level_commas, and
clean_signature for the existing unit tests.
Refactor only. Generated docs, npm run docs:reference, and npm run docs:reference:check behavior unchanged.

Linked Issue

Fixes #170

Contributor Checklist

The linked issue was marked accepted before I started.
Nobody else was assigned or already working on the issue before I started.
My branch is named issue_170.
The PR is focused on one issue with no unrelated changes.
Tests are added or updated when behavior changes.
Docs are updated when user-facing behavior changes.
Changelog is updated when the change is release-visible.
I listed the checks I ran below.

Checks Run

npm run docs:reference:check    # exit 0 (no stale diff)
npm run docs:reference          # regen clean, no docs diff
uv run --no-sync pytest tests/unit/test_generate_reference.py -q   # 24 passed

…ation tests for inject values

…ocumentation entry formatting.

…py` into focused internal modules for improved organization while maintaining existing functionality.

…rces.

greptile-apps · 2026-07-15T09:51:25Z

Greptile Summary

This PR splits the reference generator into smaller internal modules. The main changes are:

Moves page definitions, manual page loading, rendering, tables, type helpers, signatures, paths, and output handling into scripts/_reference/.
Keeps scripts/generate_reference.py as the thin CLI entrypoint.
Re-exports the signature helpers used by the existing unit tests.
Adds an unreleased changelog note for the internal docs generator refactor.

Confidence Score: 4/5

Safe to merge after removing the stray metadata file.

The reference-generator refactor keeps the same pipeline shape and no blocking behavior issue was found in the changed Python modules. Confidence is reduced for the non-blocking repository hygiene issue from committing .DS_Store.

.DS_Store

T-Rex Logs

What T-Rex did

Ran the docs reference check and it exited with code 0.
Executed the generate_reference unit tests and 24 tests passed in 0.13s.
Generated the docs reference and verified that git diff showed no changes after generation.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
.DS_Store	Adds a macOS Finder metadata binary file; this should be removed from the PR.
scripts/generate_reference.py	Reduces the CLI entrypoint to orchestration and compatibility re-exports for existing tests.
scripts/_reference/render.py	Moves page-specific markdown rendering and orchestration into a focused module; no new blocking issues found.
scripts/_reference/pages.py	Moves reference page definitions, public API parsing, and docstring validation into a focused module.
scripts/_reference/signatures.py	Moves Griffe object resolution and signature/type cleanup helpers into a focused module.
scripts/_reference/tables.py	Moves reference table constants plus signature/table validation helpers into a focused module.
scripts/_reference/types.py	Moves slug, anchor, type-link, and table-cell rendering helpers into a focused module.
scripts/_reference/manual.py	Moves manual reference passthrough and anchor validation into a focused module.
scripts/_reference/output.py	Moves write and check-mode diff output handling into a focused module.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant CLI as scripts/generate_reference.py
participant Pages as _reference.pages
participant Griffe as griffe
participant Render as _reference.render
participant Manual as _reference.manual
participant Output as _reference.output

CLI->>Pages: read_public_api()
CLI->>Pages: page_map(PAGES)
CLI->>Griffe: "load("quater", search_paths=[SOURCE_ROOT])"
CLI->>Pages: validate_public_docstrings(package, public_api)
CLI->>Render: render_reference(package, public_api, pages_by_symbol)
Render->>Manual: read_manual_reference(public_api, pages_by_symbol)
alt manual reference exists and is valid
    Manual-->>Render: existing page contents
else generated reference needed
    Render-->>Render: render index and per-page markdown
end
Render-->>CLI: outputs by path
alt --check
    CLI->>Output: check_outputs(outputs)
else write mode
    CLI->>Output: write_outputs(outputs)
end

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant CLI as scripts/generate_reference.py
participant Pages as _reference.pages
participant Griffe as griffe
participant Render as _reference.render
participant Manual as _reference.manual
participant Output as _reference.output

CLI->>Pages: read_public_api()
CLI->>Pages: page_map(PAGES)
CLI->>Griffe: "load("quater", search_paths=[SOURCE_ROOT])"
CLI->>Pages: validate_public_docstrings(package, public_api)
CLI->>Render: render_reference(package, public_api, pages_by_symbol)
Render->>Manual: read_manual_reference(public_api, pages_by_symbol)
alt manual reference exists and is valid
    Manual-->>Render: existing page contents
else generated reference needed
    Render-->>Render: render index and per-page markdown
end
Render-->>CLI: outputs by path
alt --check
    CLI->>Output: check_outputs(outputs)
else write mode
    CLI->>Output: write_outputs(outputs)
end

_{Reviews (3): Last reviewed commit: "Refactor authentication documentation: r..." | Re-trigger Greptile}

…ved readability and maintainability.

…uthConfig` in `render.py` and updated related field documentation in `tables.py` for clarity on authentication surfaces and usage.

DevilsAutumn · 2026-07-15T13:25:04Z

@utk2103 Thankyou for this PR!

Can you please squash all commits into a single commit ? Please make sure you are following the commit message convention given in our contributing guidelines.

DevilsAutumn

@utk2103 Thanks for this patch, I left few comments.

DevilsAutumn · 2026-07-31T10:22:34Z

+    ("tool", "bool", "Expose this route as an MCP tool."),
+    ("cli", "bool", "Expose this route as a Quater CLI action."),
+    ("needs_approval", "bool", "Require approval before MCP or CLI execution."),
+    ("auth", "Authenticate | None", "Route-level auth hook. See [Auth](./auth)."),


This split preserves the normal docs:reference:check path, but it leaves the generated fallback path broken. Today the command passes because read_manual_reference() finds the existing manual reference pages and returns them before these renderer tables are used.

If the manual reference directory is missing, or if we ever switch a page back to generated output, the CLI reaches render_application() and fails because these tables still describe the old route auth API. Quater.route() and RouteGroup.route() now take public: PublicSurfaces, not auth, and RouteGroup.__init__() no longer takes group-level auth.

Can you update ROUTE_OPTIONS, GROUP_ROUTE_OPTIONS, and ROUTE_GROUP_OPTIONS, and add a test that forces the generated branch? That would make this a true refactor of both supported paths: manual passthrough and generated fallback.

DevilsAutumn · 2026-07-31T10:25:58Z

+        [
+            "Quater keeps the three access surfaces explicit:",
+            "",
+            "- normal routes use `auth=...` on the route or route group.",


This prose still describes the previous auth model. The current public API uses Quater(auth=[AuthConfig(...)]) for surface-wide auth, and route-level public=... for exceptions. It no longer uses mcp_auth, cli_auth, or route/group-level auth.

Once the table mismatches are fixed, this generated page would still produce stale auth guidance, so this section should be updated as part of the refactor.

DevilsAutumn · 2026-07-31T10:30:11Z

+        "allow_credentials": "Whether browsers may include credentials.",
+        "max_age": "How long browsers may cache a preflight result.",
+    },
+    "AuthConfig": {


There is a second generated-path mismatch in the auth field docs. field_table() checks that every documented public field matches the actual object members. With the current source, AuthConfig exposes display_name, and AuthContext exposes payload, but this table only documents authenticator/surfaces/name and subject/metadata.

So render_auth() exits before it can generate the auth page. Please either document those fields here, or adjust field_table() if computed properties like display_name are intentionally not part of the reference output.

utk2103 added 6 commits July 7, 2026 20:36

Refactor inject parameter handling in route definitions and add valid…

bc6e611

…ation tests for inject values

Updated changelog and docs

30d71e5

Merge branch 'main' of https://github.com/utk2103/quater into issue_140

46cff56

Updated changelog to remove issue reference and adjusted Quickstart d…

b1e55a1

…ocumentation entry formatting.

Refactor documentation generation: split `scripts/generate_reference.…

a45021d

…py` into focused internal modules for improved organization while maintaining existing functionality.

deleted file to streamline documentation and focus on essential resou…

c3ba6c8

…rces.

greptile-apps Bot reviewed Jul 15, 2026

View reviewed changes

Comment thread scripts/_reference/render.py Outdated

utk2103 added 2 commits July 15, 2026 15:22

Clean up imports in generate_reference.py and render.py for impro…

26c5aa2

…ved readability and maintainability.

Refactor authentication documentation: replaced AuthRequest with `A…

def2fa1

…uthConfig` in `render.py` and updated related field documentation in `tables.py` for clarity on authentication surfaces and usage.

DevilsAutumn requested changes Jul 31, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fixed #170 -- Split generate_reference.py into focused internal modules - #180

Fixed #170 -- Split generate_reference.py into focused internal modules#180
utk2103 wants to merge 8 commits into
DevilsAutumn:mainfrom
utk2103:issue_170

utk2103 commented Jul 15, 2026

Uh oh!

greptile-apps Bot commented Jul 15, 2026 •

edited

Loading

Confidence Score: 4/5

T-Rex Logs

Important Files Changed

Sequence Diagram

Uh oh!

Uh oh!

DevilsAutumn commented Jul 15, 2026

Uh oh!

DevilsAutumn left a comment

Uh oh!

DevilsAutumn Jul 31, 2026

Uh oh!

DevilsAutumn Jul 31, 2026

Uh oh!

DevilsAutumn Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

utk2103 commented Jul 15, 2026

Summary

Linked Issue

Contributor Checklist

Checks Run

Uh oh!

greptile-apps Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 4/5

T-Rex Logs

Important Files Changed

Sequence Diagram

Uh oh!

Uh oh!

DevilsAutumn commented Jul 15, 2026

Uh oh!

DevilsAutumn left a comment

Choose a reason for hiding this comment

Uh oh!

DevilsAutumn Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

DevilsAutumn Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

DevilsAutumn Jul 31, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

greptile-apps Bot commented Jul 15, 2026 •

edited

Loading