You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@burr.apache.org by "enu-emu (via GitHub)" <gi...@apache.org> on 2026/06/18 00:53:16 UTC
[PR] docs: add dedicated Burr UI server documentation (issue #272) [burr]
enu-emu opened a new pull request, #810:
URL: https://github.com/apache/burr/pull/810
## Summary
Closes #272
- Creates `docs/concepts/ui.rst` with a full guide to the Burr UI server: installation, CLI options (with examples), demo data walkthrough, step-by-step descriptions of every UI feature, notebook/Colab launch, FastAPI embedding, and how to wire up tracking so your app appears in the UI
- Registers the new page in `docs/concepts/index.rst` under the Concepts toctree, positioned after `tracking`
## What's in the new page
- **Installation** — `pip install "apache-burr[start]"` with a note on the Python 3.13 / pandas compatibility fix
- **Demo Data and First Launch** — explains the four auto-copied demo projects so new users can explore immediately
- **Command-Line Options** — list-table covering `--port`, `--host`, `--no-open`, `--no-copy-demo_data`, `--backend`, and `--dev-mode` with usage examples
- **What You Can Do** — seven subsections (Browse Projects, Explore Demos, Inspect Steps, Compare State, View Source, Replay a Run, Watch Live) each with a "Try it:" instruction using the built-in demo data
- **Launch from a Notebook** — `%burr_ui` magic with Google Colab instructions
- **Embed in FastAPI** — `mount_burr_ui` example
- **Making Your App Appear** — `.with_tracker()` setup with a cross-reference to `tracking`
## Testing
- `make html` in `docs/` — Sphinx build passes, zero new warnings from the new files
- New page appears in the Concepts navigation in the built HTML output
- All CLI flags verified against `burr --help`
- All UI features verified manually using the bundled demo projects
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@burr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: add dedicated Burr UI server documentation (issue #272) [burr]
Posted by "skrawcz (via GitHub) via notifications" <no...@burr.apache.org>.
skrawcz closed pull request #810: docs: add dedicated Burr UI server documentation (issue #272)
URL: https://github.com/apache/burr/pull/810
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@burr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: add dedicated Burr UI server documentation (issue #272) [burr]
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #810:
URL: https://github.com/apache/burr/pull/810#issuecomment-5867190076
This PR has had no activity for 95 days.
Closing to keep the PR list manageable.
Feel free to reopen when you are ready to continue.
If the branch has conflicts, a fresh PR against `main` might be easier.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@burr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: add dedicated Burr UI server documentation (issue #272) [burr]
Posted by "enu-emu (via GitHub)" <gi...@apache.org>.
enu-emu commented on PR #810:
URL: https://github.com/apache/burr/pull/810#issuecomment-4794495709
Wanted to check in. Is there anything I can improve or adjust in the documentation before this gets reviewed? Happy to make any changes!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@burr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: add dedicated Burr UI server documentation (issue #272) [burr]
Posted by "skrawcz (via GitHub) via notifications" <no...@burr.apache.org>.
skrawcz commented on PR #810:
URL: https://github.com/apache/burr/pull/810#issuecomment-6550696881
# PR Review — apache/burr #810
**Title:** docs: add dedicated Burr UI server documentation (issue #272)
**Author:** enu-emu
**Branch:** `enu-emu:docs/burr-ui-server` → `apache:main`
**Type:** Documentation only (2 commits)
**Closes:** #272
**Review date:** 2026-08-29
**Base at review:** main @ `69ba3bc` (v0.43.0)
---
## Verdict: REQUEST CHANGES — do not merge as-is (superseded / redundant)
The PR is well-written and its individual technical claims are almost entirely accurate. **However, it has been overtaken by events:** a *dedicated Burr UI documentation section* was already created and merged in **PR #815** (`ce297d21`, merged 2026-06-22, closing the same underlying request #411) — after this PR was opened (2026-06-18). PR #810 now duplicates that section's scope, and it introduces a **duplicate Sphinx label warning** that directly contradicts its own "zero new warnings" testing claim.
This PR should either be **closed as superseded** or **substantially reworked** to fold its unique content (the CLI options table and the demo-data walkthrough) into the existing `docs/ui/` section instead of adding a competing page under `docs/concepts/`.
---
## What the PR changes
| File | Change |
|---|---|
| `docs/concepts/ui.rst` | **New** 270-line page: install, CLI options, demo walkthrough, UI feature tour, notebook/Colab, FastAPI embed, tracker wiring |
| `docs/concepts/index.rst` | Adds `ui` to the Concepts toctree after `tracking` |
| `.gitignore` | Adds `burr-fork/` |
---
## Blocking issues
### 1. Duplicate Sphinx label `_ui` → NEW build warning (contradicts PR claim)
`docs/concepts/ui.rst:20` declares `.. _ui:`. That label **already exists** at `docs/ui/index.rst:20` (from merged PR #815). Building the docs produces:
```
docs/ui/index.rst:24: WARNING: duplicate label ui, other instance in docs/concepts/ui.rst
```
Verified by building with Sphinx locally (`furo` + `myst-nb` + `sphinx-sitemap` + `sphinx-toolbox`). This is a **new, real warning introduced by this PR**, directly refuting the PR's testing checklist item: *"make html — Sphinx build passes, zero new warnings from the new files."* (All other warnings in the build were pre-existing autodoc import failures unrelated to this PR.)
### 2. Redundant with already-merged PR #815
PR #815 ("docs: restructure Burr UI documentation into dedicated section", merged 2026-06-22) created a full `docs/ui/` section:
- `docs/ui/index.rst` (Burr UI overview + data model)
- `docs/ui/getting-started.rst` (install, `burr`, connect app, reload/fork state)
- `docs/ui/notebook.rst` (Jupyter + Colab, `%burr_ui`)
- `docs/ui/deployment.rst`
This covers essentially the same scope as #810 (install, tracker wiring, notebook/Colab, FastAPI embed) and is already wired into the top-level `docs/index.rst` toctree. #810 adds a *second* UI page under `Concepts`, producing two competing "Burr UI" destinations and the label clash above. The idiomatic tracker example also diverges: #815 uses the recommended `.with_tracker("local", project="my-project")`; #810 uses the more verbose object form.
**Recommendation:** close #810 as superseded, or rework it to contribute only its net-new material (the CLI options table + demo-data walkthrough) into `docs/ui/getting-started.rst`.
---
## Technical accuracy of claims (validated against source @ `69ba3bc`)
All CLI/UI/API claims were checked against the actual code. Results:
| Claim in `ui.rst` | Source of truth | Verdict |
|---|---|---|
| Install via `pip install "apache-burr[start]"` | `pyproject.toml` — `start = [apache-burr[learn]]`, `learn` includes `cli` | ✅ correct |
| Bare `burr` command runs the server; accepts `--port/--host/...` | `[project.scripts] burr = "...:cli_run_server"` maps entrypoint straight to the `run_server` command | ✅ correct |
| `--port INTEGER`, default 7241 | `@click.option("--port", default=7241)` | ✅ correct |
| `--host TEXT`, default `127.0.0.1`, `0.0.0.0` for network/Docker | `@click.option("--host", default="127.0.0.1", ...)` | ✅ correct |
| `--no-open` | `@click.option("--no-open", is_flag=True)` | ✅ correct |
| `--no-copy-demo_data` | `@click.option("--no-copy-demo_data", is_flag=True)` | ✅ correct (note the odd flag spelling matches source) |
| `--backend [local\|s3]`, default `local` | `@click.option("--backend", type=click.Choice(["local","s3"]))` | ✅ correct |
| `--dev-mode` restarts on source change (uvicorn `--reload`) | `if dev_mode: cmd += " --reload"` | ✅ correct |
| Four demo projects auto-copied to `~/.burr` | `_run_server` copies `burr/tracking/server/demo_data/*`; dirs: `demo_chatbot`, `demo_chatbot_with_traces`, `demo_conversational-rag`, `demo_counter` | ✅ four projects, ⚠️ naming (see below) |
| `demo_chatbot` has 6 runs, incl. `chat-1-giraffe` | dir listing: `chat-1-giraffe` … `chat-6-demonstrate-errors` = 6 | ✅ correct |
| `chat-1-giraffe` = 30 steps | `grep -c begin_entry log.jsonl` = **30** | ✅ correct |
| `%load_ext burr.integrations.notebook` + `%burr_ui` | `burr/integrations/notebook.py` `NotebookMagics.burr_ui`, `load_ipython_extension` | ✅ correct |
| `%burr_ui` output `Burr UI: http://127.0.0.1:7241` | Only prints when `--no-iframe` is passed; **default displays an IFrame** | ⚠️ misleading (see below) |
| Colab `output.serve_kernel_port_as_window/iframe(7241)` | Generic Colab technique; the magic itself uses `google.colab.kernel.proxyPort`. PORT=7241 confirmed | ✅ works (redundant with the magic) |
| `mount_burr_ui(app, path="/burr")` from `burr.tracking.server.run` | `run.py:427 def mount_burr_ui(parent_app, path="/burr", ...)`; example exists at `examples/fastapi_mount_example.py` | ✅ correct |
| `.with_tracker(LocalTrackingClient(project="my-project"))` | `application.py:2425 with_tracker(...)` accepts a TrackingClient object; `LocalTrackingClient(project=...)` valid | ✅ correct |
| `from burr.tracking import LocalTrackingClient` | `burr/tracking/__init__.py` re-exports it | ✅ correct |
| Cross-refs `:ref:\`tracking\`` and `<trackingclientref>` | `docs/concepts/tracking.rst` defines `_tracking:` and `_trackingclientref:`; both resolve in built HTML | ✅ correct |
### Minor / non-blocking accuracy notes
- **Demo project display names.** The "First Launch" code block lists projects as `counter`, `conversational-rag`, `chatbot_with_traces`, `chatbot`, but the on-disk directories (and therefore the project names shown in the UI) are `demo_counter`, `demo_conversational-rag`, `demo_chatbot_with_traces`, `demo_chatbot`. The prose elsewhere correctly uses `demo_chatbot`. The First-Launch listing is inconsistent with the actual UI labels and with the rest of the same page.
- **Notebook output comment.** `# Output: Burr UI: http://127.0.0.1:7241` is only true with `%burr_ui --no-iframe`; the default renders an IFrame. (Note: the already-merged `docs/ui/notebook.rst` carries the identical slightly-misleading comment, so this is at least consistent with existing docs.)
- **pandas / Python 3.13 note** is plausible and harmless; not independently verified against a specific pin.
---
## Staleness & compatibility
- **Diff context is stale but merges cleanly.** The branch predates PR #893 (`human-in-the-loop`, merged 2026-08-29) which inserted a line into `docs/concepts/index.rst`. Git 3-way auto-merge resolves this without conflict (verified: `git merge --no-commit` → "Auto-merging docs/concepts/index.rst … went well"; `ui` lands correctly after `tracking`).
- **No code changes**, so no runtime/API/backward-compat risk.
- **`.gitignore` addition** (`burr-fork/`) is a personal fork-workspace artifact, not generally useful to the project — minor noise; harmless but arguably shouldn't be in this PR.
---
## Recommendation to author
1. **Preferred:** Close as superseded by #815, OR rebase and move net-new content into the existing `docs/ui/` section:
- Add the **Command-Line Options** list-table to `docs/ui/getting-started.rst` (this is genuinely useful and *not* in #815).
- Optionally add the **demo-data walkthrough** ("Try it" tour) there too.
2. **If keeping a page under `docs/concepts/`:** change/remove the `.. _ui:` label to eliminate the duplicate-label warning, and reconcile the two UI destinations so there aren't competing overviews.
3. Fix the First-Launch project names to `demo_*` to match what the UI actually shows.
4. Clarify the `%burr_ui` default behavior (IFrame vs. printed URL).
5. Drop the `.gitignore` `burr-fork/` change (personal, unrelated).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@burr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: add dedicated Burr UI server documentation (issue #272) [burr]
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] closed pull request #810: docs: add dedicated Burr UI server documentation (issue #272)
URL: https://github.com/apache/burr/pull/810
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@burr.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org