docs(py): add a documentation site for the Python package

.github/workflows/pkgdown.yaml

@@ -20,9 +20,10 @@ jobs:
     defaults:
       run:
         working-directory: pkg-r
-    # Only restrict concurrency for non-PR jobs
+    # Shared with the sibling site's workflow: both deploy to gh-pages, and
+    # two pushes to one branch race.
     concurrency:
-      group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
+      group: gh-pages-${{ github.event_name != 'pull_request' || github.run_id }}
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
     permissions:

.github/workflows/quartodoc.yaml

@@ -0,0 +1,63 @@
+on:
+  push:
+    branches: [main]
+    paths: [pkg-py/**, docs/**, .github/workflows/quartodoc.yaml]
+  pull_request:
+    paths: [pkg-py/**, docs/**, .github/workflows/quartodoc.yaml]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+name: quartodoc.yaml
+
+permissions: read-all
+
+jobs:
+  quartodoc:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: pkg-py
+    # Shared with the sibling site's workflow: both deploy to gh-pages, and
+    # two pushes to one branch race.
+    concurrency:
+      group: gh-pages-${{ github.event_name != 'pull_request' || github.run_id }}
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: quarto-dev/quarto-actions/setup@v2
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install the package and its docs dependencies
+        run: uv sync --extra shiny --group docs
+
+      - name: Build the reference pages
+        working-directory: pkg-py/docs
+        run: uv run quartodoc build
+
+      - name: Render the site
+        working-directory: pkg-py/docs
+        run: uv run quarto render
+
+      # The deploy publishes the whole of docs/, so the rendered site has to
+      # sit at the path it is served from.
+      - name: Move the site into place
+        working-directory: .
+        run: |
+          rm -rf docs/py
+          cp -r pkg-py/docs/_site docs/py
+
+      # `clean: false` so this and the pkgdown deploy can each own a
+      # subdirectory of the same branch without erasing the other.
+      - name: Deploy to GitHub pages 🚀
+        if: github.event_name != 'pull_request'
+        uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f # v4.8.0
+        with:
+          clean: false
+          branch: gh-pages
+          folder: docs

.github/workflows/verify-shared-synced.yaml

@@ -10,23 +10,37 @@ on:
       - tests/shared/**
       - prompts/**
       - www/**
+      - logos/**
+      - hex/**
       - pkg-r/tests/testthat/fixtures/shared/**
       - pkg-r/inst/prompts/**
       - pkg-r/inst/www/**
       - pkg-py/src/commons/prompts/**
       - pkg-py/src/commons/www/**
+      - pkg-py/docs/assets/logos/**
+      - pkg-py/docs/assets/figs/**
+      - pkg-py/docs/assets/hex/**
+      - docs/assets/hex/**
+      - pkg-r/pkgdown/assets/logos/**
       - scripts/sync-shared.sh
       - .github/workflows/verify-shared-synced.yaml
   pull_request:
     paths:
       - tests/shared/**
       - prompts/**
       - www/**
+      - logos/**
+      - hex/**
       - pkg-r/tests/testthat/fixtures/shared/**
       - pkg-r/inst/prompts/**
       - pkg-r/inst/www/**
       - pkg-py/src/commons/prompts/**
       - pkg-py/src/commons/www/**
+      - pkg-py/docs/assets/logos/**
+      - pkg-py/docs/assets/figs/**
+      - pkg-py/docs/assets/hex/**
+      - docs/assets/hex/**
+      - pkg-r/pkgdown/assets/logos/**
       - scripts/sync-shared.sh
       - .github/workflows/verify-shared-synced.yaml
   workflow_dispatch:

.gitignore

@@ -6,6 +6,7 @@
 .Rproj.user
 .Rprofile
 /docs/r/
+/docs/py/
 plans/
 rsconnect/
 CLAUDE.local.md

docs/index.html

@@ -9,23 +9,23 @@
   <meta property="og:title" content="commons">
   <meta property="og:description" content="commons helps data scientists build trustworthy data agents.">
   <meta property="og:url" content="https://posit-dev.github.io/commons/">
-  <meta property="og:image" content="https://posit-dev.github.io/commons/assets/commons-logo.png">
-  <link rel="icon" href="assets/commons-logo.png" type="image/png">
+  <meta property="og:image" content="https://posit-dev.github.io/commons/assets/hex/commons-hex.png">
+  <link rel="icon" href="assets/hex/commons-hex.png" type="image/png">
   <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
   <link rel="stylesheet" href="styles.css">
   <script src="site.js" defer></script>
 </head>
 <body>
   <main>
     <header class="title-block">
-      <img class="logo" src="assets/commons-logo.png" alt="The package's hex sticker; a Common Kingfisher drawn in a cartoonish style, sitting on a park bench with a plaque reading 'commons'. Behind the bird is an open green space." width="120" height="139">
+      <img class="logo" src="assets/hex/commons-hex.png" alt="The package's hex sticker; a Common Kingfisher drawn in a cartoonish style, sitting on a park bench with a plaque reading 'commons'. Behind the bird is an open green space." width="120" height="139">
       <h1>commons</h1>
       <p class="subtitle">An R and Python package that helps data scientists build trustworthy data analysis agents.</p>
     </header>
 
     <nav class="package-links" aria-label="Package documentation">
-      <a href="r/"><i class="fa-brands fa-r-project" aria-hidden="true"></i> R</a>
-      <a href="https://github.com/posit-dev/commons/tree/main/pkg-py"><i class="fa-brands fa-python" aria-hidden="true"></i> Python</a>
+      <a href="r/"><i class="fa-brands fa-r-project" aria-hidden="true"></i> R Documentation</a>
+      <a href="py/"><i class="fa-brands fa-python" aria-hidden="true"></i> Python Documentation</a>
       <a href="https://github.com/posit-dev/commons"><i class="fa-brands fa-github" aria-hidden="true"></i> GitHub</a>
     </nav>
 
@@ -42,7 +42,7 @@ <h1>commons</h1>
 
     <pre><code>install.packages("commons")</code></pre>
 
-    <p>To install the Python package from PyPI, run:</p>
+    <p>To install the <a href="https://pypi.org/project/commons/">Python package from PyPI</a>, run:</p>
 
     <pre><code>pip install commons</code></pre>
 
@@ -70,7 +70,7 @@ <h2>Get started</h2>
 
     <p>To get started with the R package, check out the <a href="r/articles/commons.html">introductory vignette</a>. The package ships with an <a href="r/articles/commons.html#working-with-the-agent-skill">agent skill</a> to help you hook your trusted code and context up to the agent.</p>
 
-    <p>The Python package is based on the same ideas, so the linked vignette from the R package will give you a sense of where the package is going. (The resulting apps will look <em>very</em> similar regardless of whether you use R or Python—they literally share the same CSS!) Check out the <a href="https://github.com/posit-dev/commons/tree/main/pkg-py">package README</a> to learn more.</p>
+    <p>To get started with the Python package, check out the <a href="py/">introduction</a>. (The resulting apps will look <em>very</em> similar regardless of whether you use R or Python—they literally share the same CSS!)</p>
     </section>
   </main>
 </body>

hex/README.md

@@ -0,0 +1,7 @@
+# Hex sticker
+
+`commons-hex.png` is the package's hex sticker, shown on the landing page and at the top of the Python site's home page. It is a web-sized reduction of `pkg-r/inst/hex/commons.png`, which `pkg-r/inst/hex/make_hex.py` generates from the source artwork.
+
+`scripts/sync-shared.sh` copies this directory into `docs/assets/hex/` and `pkg-py/docs/assets/hex/`, and CI fails when a copy is stale. Edit the file here, never a copy.
+
+The R site does not get a copy: pkgdown picks the sticker up from `pkg-r/man/figures/logo.png` by convention, which is also what the R README embeds.

logos/README.md

@@ -0,0 +1,10 @@
+# Site logos
+
+The language marks the documentation site navbars show: `python-logo.svg`
+beside the Python site's title, and `r-logo.svg` both beside the R site's
+title and as the Python site's link to the R site. The Python mark is the
+PSF's (via Wikimedia); the R mark is from r-project.org (CC BY-SA 4.0).
+
+`scripts/sync-shared.sh` copies this directory into `pkg-py/docs/assets/logos/`
+and `pkg-r/pkgdown/assets/logos/`, and CI fails when a copy is stale. Edit the
+files here, never a copy.

pkg-py/.gitignore

@@ -14,3 +14,6 @@ dist/
 
 # Jupyter writes these beside a notebook; they carry outputs and local paths.
 .ipynb_checkpoints/
+
+/.quarto/
+**/*.quarto_ipynb

pkg-py/README.md

@@ -33,8 +33,8 @@ def region_revenue(
 
 
 agent = commons.Commons(
-    chatlas.ChatAnthropic(model="claude-sonnet-5"),
-    commons.data_source(sales=sales, dictionary="data-dict.yaml"),
+    client=chatlas.ChatAnthropic(model="claude-sonnet-5"),
+    data_sources=commons.data_source(sales=sales, dictionary="data-dict.yaml"),
     semantic_layer=commons.semantic_layer(region_revenue),
     context_layer=commons.context_layer(files=["reporting-policy.md"]),
 )

pkg-py/demo.ipynb

@@ -318,8 +318,8 @@
     ")\n",
     "\n",
     "mine = commons.Commons(\n",
-    "    demo.client(),\n",
-    "    {'warehouse': commons.data_source(stands=demo.stands, surveys=demo.surveys)},\n",
+    "    client=demo.client(),\n",
+    "    data_sources={'warehouse': commons.data_source(stands=demo.stands, surveys=demo.surveys)},\n",
     "    semantic_layer=layer,\n",
     "    context_layer=commons.context_layer(files=[demo.notes_file()]),\n",
     ")\n",

pkg-py/demo.py

@@ -221,9 +221,9 @@ def client() -> chatlas.Chat:
 def agent() -> commons.Commons:
     """The canopy agent, over all three layers."""
     return commons.Commons(
-        client(),
+        client=client(),
         # Named, because a measure's `warehouse` argument is injected by name.
-        {"warehouse": commons.data_source(stands=stands, surveys=surveys)},
+        data_sources={"warehouse": commons.data_source(stands=stands, surveys=surveys)},
         semantic_layer=commons.semantic_layer(
             canopy_by_county, low_canopy_stands, canopy_headline
         ),

pkg-py/docs/.gitignore

@@ -0,0 +1,6 @@
+/reference/
+/_site/
+/.quarto/
+/objects.json
+
+**/*.quarto_ipynb

pkg-py/docs/_quarto.yml

@@ -0,0 +1,95 @@
+project:
+  type: website
+  # Renders in place, because Quarto warns when its output directory sits
+  # outside the project. The deploy workflow copies _site into docs/py.
+  output-dir: _site
+  # Explicit, so the design notes under notes/ stay out of the site.
+  render:
+    - index.qmd
+    - get-started.qmd
+    - governance.qmd
+    - feature-parity.qmd
+    - reference/*.qmd
+
+website:
+  title: "commons"
+  site-url: https://posit-dev.github.io/commons/py/
+  repo-url: https://github.com/posit-dev/commons
+  repo-subdir: pkg-py
+  navbar:
+    logo: assets/logos/python-logo.svg
+    left:
+      - href: get-started.qmd
+        text: Get started
+      - href: governance.qmd
+        text: Security and governance
+      - href: feature-parity.qmd
+        text: Feature parity
+      - href: reference/index.qmd
+        text: API Reference
+    right:
+      - text: '<span class="r-logo" title="R Documentation">R Documentation</span>'
+        href: ../r/
+      - icon: box-seam
+        href: https://pypi.org/project/commons/
+        aria-label: commons on PyPI
+      - icon: github
+        href: https://github.com/posit-dev/commons
+  sidebar:
+    - id: reference
+      contents: reference/_sidebar.yml
+  page-footer:
+    left: "Developed by Josh Taillon, Posit Software, PBC."
+    right: "Site built with [Quarto](https://quarto.org/)."
+
+format:
+  html:
+    theme: cosmo
+    toc: true
+    css: assets/styles.css
+
+metadata-files:
+  - reference/_sidebar.yml
+
+quartodoc:
+  package: commons
+  title: Reference
+  style: pkgdown
+  dir: reference
+  sidebar: reference/_sidebar.yml
+  render_interlinks: false
+  renderer:
+    style: markdown
+    table_style: description-list
+  sections:
+    - title: Main functions
+      desc: |
+        The main agent constructor, plus the building blocks for a commons agent.
+      contents:
+        - Commons
+        - data_source
+        - semantic_layer
+        - measure
+        - context_layer
+    - title: Supporting types
+      desc: |
+        The objects the constructors return, and the values they carry.
+      contents:
+        - DataSource
+        - SemanticLayer
+        - ContextLayer
+        - Measure
+        - Injected
+        - Tag
+        - list_tables
+    - title: Shiny UI and server
+      desc: |
+        Put a commons agent inside of an interactive chat app. Needs the
+        `shiny` extra.
+      package: commons.ui
+      contents:
+        - app
+        - server
+        - theme
+        - commons_chat_dependency
+        - asset_base_url