Repository navigation
ci: fail the docs build on schema tables that rendered wrong - #1007
sakinaroufid wants to merge 1 commit into
Conversation
The field tables on the spec pages are generated from the schemas and OpenAPI documents. When the macro cannot name a type, the build still succeeds and the cell reads "any", "OneOf[]", "Array[any]" or nothing. That has reached the published site five times (Universal-Commerce-Protocol#352, Universal-Commerce-Protocol#465, Universal-Commerce-Protocol#549, Universal-Commerce-Protocol#552, Universal-Commerce-Protocol#894), each found by someone reading the page, and the Location REST binding shipped without its headers table the same way (Universal-Commerce-Protocol#784). Every fix added a test for the case it found; nothing checked the next one. Add scripts/check_rendered_tables.py and run it after the build in both verify jobs, next to check_links.py. Over the built HTML it asserts that every Name / Type / Requirement / Description table has a named type in each row, that every REST binding page renders its HTTP Headers table, and that every response_*_schema definition in ucp.json has a rendered section. Hand-written tables with other headers are left alone. Unit tests run from pre-commit like the other script tests. The first run against main found a live case: amenity_type.json is a $ref to reverse_domain_name.json, a string with a pattern. The macro emitted the table header and then the type's prose, which Markdown read as a one-cell row with an empty Type, on the location REST and MCP pages and the reference page. A $ref that resolves to prose is now returned without the header, so Amenity Type renders like Reverse Domain Name does. The macro tests pin it. Verified: full draft build, check_links and the new check pass; test_schema_tables 18 passed; test_check_rendered_tables 16 passed.
|
Splitting this up. The test vectors and the signed-example verification have moved to #1008, rebased onto current main and extended to cover every inline example on the spec pages, not only the vectors section. That part is Infrastructure/Documentation and can go through maintainer review on its own. The two normative changes here, the order webhook delivery contract and the ready_for_complete definition for checkout, need Tech Council review and will each get a separate PR once #1008 lands, so their diffs show only the rule change. Leaving this open until then as the reference for those two. |
|
nvm - decided to close this in favour of #1008, which carries the test vectors rebased on main and extends verification to every signed example in the spec. The order webhook delivery contract and the |
Description
Adds a post-build check for the generated field tables and wires it into docs.yml after check_links.py.
Background: #352, #465, #549, #552, #894 were all the same bug class. _render_table_from_schema couldn't name a type, so the Type cell came out as
any/OneOf[]/Array[any]/ blank, and the build was green. #784 is the headers-table version of it. All of those were caught by reading the published page, and all the fixes pinned the specific path in test_schema_tables.py, which is fine but doesn't help with the next path.check_rendered_tables.py parses the built html (local_preview or site) and fails on:
Name|Type|Requirement|Descriptiontable row with Type empty,any,*[any],*[]or containing{/}specification/**/rest/index.htmlpage with noHeader|Required|Descriptiontableresponse_*_schemadef in ucp.json with noucp-response-*-schemaid anywhere in the siteMatching on the exact macro header keeps it off the hand-written tables (payment/template.md has
{type}cells on purpose, a few enum tables have a Type column with lowercase values). mike's redirect pages are skipped by title.Running it on main found a live one. amenity_type.json is only a $ref to reverse_domain_name.json, which is a string+pattern. The
elif "$ref" in schema_databranch appended the ref's output under the table header, the ref rendered as prose (description + Pattern:), and python-markdown treats a non-blank line after the separator row as a table row. Result: on location/rest, location/mcp and reference.md the Amenity Type section is a 4-col table with the whole description sitting in the Name column. The change in main.py returns the body on its own when it isn't table rows. Reverse Domain Name on reference.md already renders that way. Test added.Pre-commit runs test_check_rendered_tables.py on changes to the two scripts, same pattern as the other script tests. AGENTS.md lists the command next to check_links.
Not covered: anything the check doesn't know to look for. It's a tripwire for the shapes we've already been bitten by, not a schema-vs-table diff.
Category (Required)
Related Issues
#352 #465 #549 #552 #784 #894
Checklist
!for breaking changes).Screenshots / Logs (if applicable)
main, without the main.py change:
this branch: