docs(py): add a documentation site for the Python package - #366
Draft
jat255 wants to merge 4 commits into
Draft
Conversation
Set up a Quarto project under pkg-py/docs that builds the API reference with quartodoc. The reference sections match the ones the R site groups its topics into, minus trajectories, which the Python package does not have. The site renders in place, and the workflow copies it to docs/py before the deploy, because Quarto warns and declines to clean its own output when the output directory sits outside the project. The deploy reuses the pkgdown workflow's action and its clean: false setting, so each site owns a subdirectory of gh-pages without erasing the other. griffe is held below 2 because quartodoc 0.11.1 passes it a docstring parser option that griffe 2 removed. Building the reference surfaced a docstring defect in commons.ui.server(): a closing paragraph sat inside the numpydoc Parameters block, so its words were parsed as parameter names. Moved it above the block.
The introduction covers the ground the R vignette covers: the trust flow and where each provenance outcome comes from, the semantic and context layers, data sources and dictionaries, and the chat UI. It leaves out what the Python package does not have, rather than describing the R behaviour: there is no code-execution path in the outcome table, no warehouse semantic layer section, and no agent skill or trajectory review. The governance page answers the same questions for Python. Two differences from the R page carry weight. The SQL check parses the statement with sqlglot and allowlists read-only shapes, so it catches writes hidden inside a read that a first-word test admits. And no tool runs model-written code, so the sandboxing, network, and subprocess material has no counterpart; the page says so plainly instead of leaving the question open. The landing page's Python button and get-started paragraph now point at the site rather than at the package README on GitHub.
Both site workflows push to gh-pages, and a release or a change under docs/ triggers both. With a concurrency group each, the two runs could push at the same time and one site's update would be lost. One shared group for non-PR runs makes the second wait instead.
The introduction said definitions compile to the dialect of the source, with no limit. Only DuckDB, Snowflake, and Databricks have an emitter, so a PostgreSQL engine carrying a dictionary with definitions fails at construction. The page now states that alongside the other construction errors. The governance page enumerated the SQL guard's allowlist and got the enumeration short: _READ_ONLY also holds Subquery, Values, and Pivot. It now gives SELECT and the set operations as examples rather than as the whole set, and describes the rejected forms as the tree search the guard performs instead of as a flat keyword list.
jat255
added
documentation
jat255
added this pull request to stack #367
September 12, 2026 15:51
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR adds a documentation site for the Python package at
/py/: a quartodoc API reference, an introduction page, and a security and governance page. The landing page's Python button now points there rather than at the package README on GitHub.Stacked on #365, so this targets
shared-siteuntil that lands.Refs kata 3w6z.
Agent-written detail on what the pages claim
The pages cover the ground the R vignettes cover, and leave out what the Python package does not have rather than describing the R behaviour: no code-execution row in the provenance-outcome table, no warehouse semantic layer section, no agent skill or trajectory review.
That matters most on the governance page. No tool runs model-written Python, so the sandboxing, network, and subprocess material has no counterpart, and the page says so plainly instead of leaving the question open. Going the other way, the SQL check parses with sqlglot and allowlists read-only statement shapes, so it catches writes hidden inside a read that a first-word test admits.
Two claims drafted from R behaviour were wrong for Python and were corrected before filing: definitions compile only for DuckDB, Snowflake, and Databricks, and the guard's allowlist is wider than
SELECTplus the set operations.The two deploy workflows now share one non-PR concurrency group, because both push to
gh-pagesand a release triggers both.Verified: ruff, pyrefly, and the 1499 pytest cases pass; the site builds clean from a fresh venv using the workflow's own install command; all eight external links and three internal anchors resolve.