docs: restructure Burr UI documentation into dedicated section (#411)

docs/index.rst

@@ -25,6 +25,7 @@
    :caption: Apache Burr
 
    getting_started/index
+   ui/index
    examples/index
    concepts/index
    reference/index

docs/ui/deployment.rst

@@ -0,0 +1,58 @@
+..
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+
+.. _ui-deployment:
+
+==========
+Deployment
+==========
+
+The Burr tracking server can be run locally for development or deployed alongside your
+production stack for ongoing observability.
+
+--------------------------
+Embed in a FastAPI App
+--------------------------
+
+Mount the Burr UI inside an existing FastAPI application using the ``mount_burr_ui`` helper:
+
+.. code-block:: python
+
+    from fastapi import FastAPI
+    from burr.tracking.server.run import mount_burr_ui
+
+    app = FastAPI()
+    mount_burr_ui(app, path="/burr")
+
+The tracking UI will then be available at ``/burr`` on your existing server.
+
+--------------------
+Production Options
+--------------------
+
+For production deployments, Burr supports two tracking backends:
+
+1. **Local filesystem** (default) — suitable for development or lower-scale production
+   with a distributed filesystem. See :ref:`tracking` for configuration details.
+
+2. **S3-backed tracking** — designed for higher-scale production workloads.
+   See :ref:`s3-tracking-aws` for setup instructions.
+
+For full deployment examples including Docker Compose and nginx, see
+:doc:`../examples/deployment/monitoring`.

docs/ui/getting-started.rst

@@ -0,0 +1,89 @@
+..
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+
+.. _ui-getting-started:
+
+===============
+Getting Started
+===============
+
+-----------
+Quick Start
+-----------
+
+Install Burr with the UI extras and launch the server:
+
+.. code-block:: bash
+
+    pip install "apache-burr[start]"
+    burr
+
+This starts the tracking server on port ``7241`` and opens the UI in your browser.
+
+------------------
+Connect Your App
+------------------
+
+Any application that uses :py:meth:`with_tracker <burr.core.application.ApplicationBuilder.with_tracker>`
+will automatically appear in the UI:
+
+.. code-block:: python
+
+    from burr.core import ApplicationBuilder
+
+    app = (
+        ApplicationBuilder()
+        .with_actions(...)
+        .with_transitions(...)
+        .with_tracker("local", project="my-project")
+        .build()
+    )
+
+Run your application and then open ``http://localhost:7241`` to see your project,
+its application runs, and the step-by-step trace.
+
+-----------------------
+Reloading Prior State
+-----------------------
+
+Because the tracking client writes to the local filesystem (``~/.burr`` by default), you
+can reload state from any past run for debugging:
+
+.. code-block:: python
+
+    from burr.tracking import LocalTrackingClient
+
+    tracker = LocalTrackingClient(project="my-project")
+    app = (
+        ApplicationBuilder()
+        .with_graph(base_graph)
+        .initialize_from(
+            tracker,
+            resume_at_next_action=True,
+            default_state={},
+            default_entrypoint="my-entrypoint",
+            fork_from_app_id="<prior-app-id>",
+            fork_from_sequence_id=None,
+            fork_from_partition_key=None,
+        )
+        .with_tracker(tracker)
+        .build()
+    )
+
+See :ref:`tracking` for the full tracking client reference.

docs/ui/index.rst

@@ -0,0 +1,50 @@
+..
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+
+.. _ui:
+
+=======
+Burr UI
+=======
+
+Burr comes with an open-source telemetry UI for monitoring, debugging, and replaying
+your application runs in real time. It works locally out of the box and can also be
+deployed alongside your production stack.
+
+.. image:: ../_static/chatbot.png
+    :alt: Burr UI showing a chatbot application graph
+    :align: center
+
+----------
+Data Model
+----------
+
+The UI is organized around three levels:
+
+1. **Projects** — the top-level grouping, set via the ``project`` argument to ``with_tracker``.
+2. **Applications** — individual runs logged to a project, similar to a "trace" in distributed tracing. Set via the ``app_id`` argument.
+3. **Steps** — each action executed in the state machine. The UI shows the state, inputs, and results at every step.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   getting-started
+   notebook
+   deployment

docs/ui/notebook.rst

@@ -0,0 +1,58 @@
+..
+   Licensed to the Apache Software Foundation (ASF) under one
+   or more contributor license agreements.  See the NOTICE file
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
+
+
+.. _ui-notebook:
+
+================
+Notebook / Colab
+================
+
+You can launch the Burr UI directly from a Jupyter notebook or Google Colab using the
+``%burr_ui`` IPython magic, without needing a separate terminal.
+
+------------------
+Jupyter Notebook
+------------------
+
+.. code-block:: python
+
+    # Load the extension and print the URL
+    %load_ext burr.integrations.notebook
+    %burr_ui
+    # → "Burr UI: http://127.0.0.1:7241"
+
+The magic starts the tracking server on port ``7241`` if it isn't already running and
+prints the URL to access it.
+
+--------------
+Google Colab
+--------------
+
+In Colab, the kernel runs remotely, so you need to forward the port to your browser:
+
+.. code-block:: python
+
+    %load_ext burr.integrations.notebook
+    %burr_ui
+
+.. code-block:: python
+
+    from google.colab import output
+    output.serve_kernel_port_as_window(7241)   # opens a new browser window
+    output.serve_kernel_port_as_iframe(7241)   # or inline as an iframe