Repository navigation
docs(py): add a documentation site for the Python package - #366
Merged
Merged
Conversation
jat255
added
documentation
jat255
added this pull request to stack #367
September 12, 2026 15:51
Contributor
|
Preview deployed to Connect ( Deployed from commit a29f449. |
Contributor
|
Preview deployed to Connect ( Deployed from commit a29f449. |
simonpcouch
force-pushed
the
jat255/3w6z-python-docs-site
branch
from
September 13, 2026 20:41
6eb4e83 to
3677a7d
Compare
jat255
force-pushed
the
jat255/3w6z-python-docs-site
branch
from
September 13, 2026 21:29
3677a7d to
8f6e2ee
Compare
jat255
removed
the
needs-manual-review
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.
Move the two navbar language marks to logos/ at the repository root and sync them into both documentation sites, like the other shared sources. The copies are served as they stand, so destinations marked :bare skip the generated README.
Show the R logo beside the package name and a Python-logo link to the Quarto site in the navbar, mirroring the Python site. The link is absolute because the dev-mode site builds under /r/dev/. The R logo is the synced copy under pkgdown/assets/logos/.
Mirror the R docs structure: the root page is a general introduction with installation instructions, and Introduction to commons moves to its own Get started page.
Sync the shared provenance-marker figs into the docs assets, port the vignette's inline-marker CSS rule, and mark the example verified answer in the blockquote, as the R vignette does.
…visual provenance markers to outcomes table
Add the provenance markers to the outcomes table, rewrite the measure-parameter paragraph in plainer English with an example, give examples for table selection and warehouse catalogs, and use named client=/data_sources= arguments in every user-facing Commons() call, as the constructor names them.
Mirror the pkgdown footer: developer credit on the left, a Built with Quarto link on the right.
…emo application links
jat255
force-pushed
the
jat255/3w6z-python-docs-site
branch
from
September 13, 2026 22:09
ff748d9 to
a3c12bf
Compare
jat255
marked this pull request as ready for review
September 13, 2026 22:09
jat255
force-pushed
the
jat255/3w6z-python-docs-site
branch
from
September 13, 2026 22:45
b58767a to
4ca7918
Compare
jat255
removed this pull request from stack #367
September 13, 2026 22:47
jat255
added this pull request to stack #371
September 13, 2026 22:47
The sticker becomes a synced root artifact so the landing page and the Python site share one source, rather than each carrying its own copy. The R site keeps taking it from man/figures/logo.png, pkgdown's convention.
The root README already linked it; the landing page and the Python site named PyPI without linking it.
Documentation in [project.urls] puts the site in PyPI's sidebar, which had only the repository and the issue tracker.
simonpcouch
approved these changes
Sep 14, 2026
simonpcouch
left a comment
simonpcouch
left a comment
Collaborator
There was a problem hiding this comment.
Nice, looks good!
FYI, the pkgdown Action to publish the production version of https://posit-dev.github.io/commons/r/ (e.g. 0.1.0) will not push to the main site after merging here since the R DESCRIPTION version is now dev 0.1.0.9000. It's a bit fiddly to get this right; I can make it happen after merge.
Contributor
|
Cleaned up 10 preview bundle(s) on https://dogfood.team.pct.posit.it: 370328, 370331, 370334, 370338, 370339, 370340, 370342, 370343, 370346, 370347 |
Contributor
|
Cleaned up 10 preview bundle(s) on https://connect.staging.pct.posit.it: 2893, 2894, 2895, 2898, 2899, 2900, 2901, 2902, 2904, 2905 |
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
2 participants
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, a security and governance page, and a page describing the feature parity with the R implementation. The landing page's Python button now points there rather than at the package README on GitHub.You can see what these look like from the nifty new doc preview action from #370:
R changes
The changes are only in the documentation — no package code changes with this PR.
_pkgdown.ymlgains a navbar item on the right that links to the new Python site athttps://posit-dev.github.io/commons/py/extra.cssputs the R logo before the package name in the navbar via a.navbar-brand::beforerule, matching how the Python site shows its logo, with the two logo SVGs added underpkgdown/assets/logos/via the root-level asset syncing described in the next sectionThe logos and figures are handled by the existing root-artifact syncing:
logos/directory is the single source for the two language marks, andscripts/sync-shared.shcopies it intopkg-py/docs/assets/logos/andpkg-r/pkgdown/assets/logos/; the Python site's provenance marker SVGs come from the already-sharedwww/commons-chat/figs, copied intopkg-py/docs/assets/figs/.verify-shared-synced.yamlpicks up the new source and destination paths so CI fails on a stale copy.Screenshots
Python home page
Note the python logo in the top left, and a link to the R version of the package on the top right
API Reference built with quartodoc
R homepage, showing R logo in top left and link to python package in top right:
Agent-written details
Refs kata 3w6z.
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.