docs: update api reference (#4316)

* update

* update versioning, session docs

api_reference/README.md

@@ -8,6 +8,7 @@ Maintaining the API reference consists of two parts:
 2. Hosting and CI with readthedocs
 
 ## Configuration
+
 ```
 api_reference
  ┣ source
@@ -31,36 +32,47 @@ api_reference
 
 - conf.py: All sphinx-related configuration is done here and is necessary to run Sphinx.
 - index.md: Main entrypoint for the API reference. This file must be in the `source` directory.
-- requirements.txt: Requirements necessary for readthedocs.
+- requirements.txt: This file is necessary for readthedocs to manage dependecies.
 - make files: Not required but useful in generating static HTML pages locally.
 
+To run and build locally, download all dependencies found in `requirements.txt` (especially packages/phoenix-evals as a dev dependency `-e`).
+
 ## Building the Documentation
 
 ### Api-doc
-We must first generate the documentation using Markdown or reStructuredText files that contain Sphinx autodoc directives. This is done automatically using sphinx-apidoc (which outputs rst files). The typical command used for this API reference is:
+
+If the API reStructuredText (rst) or Markdown (md) files are already present in the `api` directory, skip this step and modify those files directly.
+
+If you are starting from scratch or want to re-generate those pages, you must first generate the documentation using Markdown or reStructuredText files that contain Sphinx autodoc directives. This is done automatically using sphinx-apidoc (which outputs rst files). However, content that was manual edits such as examples, page organization, module autodoc settings, etc. will be lost. The typical command used for this API reference is:
 
 ```
 sphinx-apidoc -o ./source/output ../path/to/module --separate -M
 ```
 
 where `path/to/module` refers to the module.
 
-This automatically generates reStructuredText with autodoc-related directives for all modules of the specified package.
+This automatically generates reStructuredText with autodoc-related directives for all modules of the specified package. These files direct Sphinx when building on how to generate our documentation from the docstrings in our codebase.
 
 ### Autodoc
+
 The files generated using apidoc can be edited to specify certain documentation generation behavior using directive options. Autodoc directives instruct the autodoc extension to extract docstrings from files and automatically generate API documentation. Autodoc directives (for rst) typically look something like:
+
 ```
 .. automodule:: module_name
    :members:
 ```
+
 where `.. automodule:: module_name` is an autodoc directive and `:members` is a directive option.
 
 Documentation (and a list of all directive options) for Sphinx can be found here:
+
 - https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html
 - https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
 
 ### HTML Static Sites
-Once the rst files are created, for the documentation to be rendered, index.md should have some way to reach them in its toctree. After the correct path setup, make the static HTML sites using:
+
+Once the rst files are created using autdoc, for the documentation to be rendered, index.md should have some way to reach them in its toctree. After the correct path setup, make the static HTML sites using:
+
 ```
 make clean
 make html
@@ -71,12 +83,17 @@ or
 ```
 make clean html
 ```
-and the HTML sites should be built in the `build` directory. All custom static files should go in `_static`.
+
+and the HTML sites should be built in the `build` directory.
+
+Note: All custom static files should be placed in `_static`.
 
 ## PyData Theme
+
 The PyData theme that we use for our API reference has its own theme-related configurations that change the behavior of Sphinx. These configuration options can be found here: https://pydata-sphinx-theme.readthedocs.io/en/stable/
 
 ## Readthedocs
+
 Configurations for readthedocs is found in the root directory as `.readthedocs.yaml`. It must have the correct path to both Sphinx's `conf.py` file and to the `requirements.txt` in the API reference's directory. Once there are valid rst or md files for Phoenix's modules, a valid `.readthedocs.yaml`, and valid `conf.py`, readthedocs will automatically build our documentation. When a new commit is pushed to the Phoenix repository, readthedocs receives a webhook and a new build of the references is rendered to match the new commit. Whenever a new tag is updated on the repo, that tag will also be automatically built and updated to be public as per settings set on `Automation Rules` on readthedocs.
 
 Version control for the reference's version dropdown must be manually be updated in `switcher.json`.

api_reference/source/_static/switcher.json

@@ -4,33 +4,32 @@
         "url": "https://arize-phoenix.readthedocs.io/en/latest/",
         "preferred": true
     },
+    {
+        "version": "v4.25.0",
+        "url": "https://arize-phoenix.readthedocs.io/en/arize-phoenix-v4.25.0/"
+    },
+    {
+        "version": "v4.20.0",
+        "url": "https://arize-phoenix.readthedocs.io/en/arize-phoenix-v4.20.0/"
+    },
+    {
+        "version": "v4.15.0",
+        "url": "https://arize-phoenix.readthedocs.io/en/arize-phoenix-v4.15.0/"
+    },
     {
         "version": "v4.12.0",
         "url": "https://arize-phoenix.readthedocs.io/en/arize-phoenix-v4.12.0/"
     },
     {
-        "name": "4.11.0",
         "version": "v4.11.0",
         "url": "https://arize-phoenix.readthedocs.io/en/arize-phoenix-v4.11.0/"
     },
     {
-        "name": "4.10.1",
         "version": "v4.10.1",
         "url": "https://arize-phoenix.readthedocs.io/en/arize-phoenix-v4.10.1/"
     },
     {
-        "name": "4.9.0",
         "version": "v4.9.0",
         "url": "https://arize-phoenix.readthedocs.io/en/arize-phoenix-v4.9.0/"
-    },
-    {
-        "name": "4.8.1",
-        "version": "v4.8.1",
-        "url": "https://arize-phoenix.readthedocs.io/en/arize-phoenix-v4.8.1/"
-    },
-    {
-        "name": "4.7.2",
-        "version": "v4.7.2",
-        "url": "https://arize-phoenix.readthedocs.io/en/arize-phoenix-v4.7.2/"
     }
 ]

api_reference/source/api/session.rst

@@ -7,25 +7,118 @@ phoenix.launch_app
 ------------------
 .. automethod:: session.session::launch_app
 
+   **Usage**
+
+      Launch Phoenix as a collector of LLM Traces generated by your LLM applications.
+      By default the collector listens on port 6006::
+
+         import phoenix as px
+
+      Launch Phoenix with primary and reference inferences `prim_inf_` and `ref_inf_`,
+      both instances of Inferences, with::
+
+         session = px.launch_app(prim_inf_, ref_inf_)
+
+      Alternatively, launch Phoenix with a single dataset inf, an instance of Inferences, with::
+
+         session = px.launch_app(inf)
+
+      Then session is an instance of Session that can be used to open the Phoenix UI in an inline
+      frame within the notebook or in a separate browser tab or window.
+
 phoenix.active_session
 ----------------------
 .. automethod:: session.session::active_session
 
+   **Usage**
+
+      Suppose you previously ran::
+
+         px.launch_app()
+
+      without assigning the returned Session instance to a variable.
+      If you later find that you need access to the running session object, run::
+
+         session = px.active_session()
+
+      Then session is an instance of Session that can be used to open the Phoenix UI
+      in an inline frame within your notebook or in a separate browser tab or window.
+
 phoenix.close_app
 -----------------
 .. automethod:: session.session::close_app
 
+   .. warning::
+      The Phoenix server will continue running in the background until it is explicitly closed, even if the Jupyter server and kernel are stopped.
+
 phoenix.delete_all
 ------------------
 .. automethod:: session.session::delete_all
 
 phoenix.Session
 ---------------
-A session that maintains the state of the Phoenix app. Obtain the active session as follows::
+   A session that maintains the state of the Phoenix app. Obtain the active session as follows::
+
+      session = px.active_session()
 
-   session = px.active_session()
+.. warning::
 
-|
+   Phoenix users should not instantiate their own phoenix.Session instances.
+   They interact with this API only when an instance of the class is returned by launch_app or active_session.
 
 .. autoclass:: session.session::Session
    :members:
+   :exclude-members: active, end, trace_dataset
+
+**Usage**
+
+   Launch Phoenix with primary and reference inferences prim_inf and ref_inf, both instances of phoenix.Dataset, with::
+
+      session = px.launch_app(prim_inf, ref_inf)
+
+   Alternatively, launch Phoenix with a single dataset ds, an instance of phoenix.Dataset, with::
+
+      session = px.launch_app(inf)
+
+   Open the Phoenix UI in an inline frame within your notebook with::
+
+      session.view()
+
+   You can adjust the height of the inline frame by passing the desired height (number of pixels) to the height parameter.
+   For example, instead of the line above, run::
+
+      session.view(height=1200)
+
+   to open an inline frame of height 1200 pixels.
+
+   As an alternative to an inline frame within your notebook, you can open the Phoenix UI in a new browser tab or window by running::
+
+      session.url
+
+   and copying and pasting the URL.
+
+   Once a cluster or subset of your data is selected in the UI, it can be saved by clicking the "Export" button.
+   You can then access your exported data in your notebook via the exports property on your session object, which returns a
+   list of dataframes containing each export.
+
+   ..code::
+
+      session.exports
+
+   Exported dataframes are listed in chronological order. To access your most recent export, run::
+
+      session.exports[-1]
+
+**Get LLM Spans As DataFrame**
+
+   Get all available spans. See LLM Traces on how to trace your LLM applications.::
+
+      session.get_spans_dataframe()
+
+   Get spans associated with calls to LLMs.::
+
+      session.get_spans_dataframe("span_kind == 'LLM'")
+
+   Get spans associated with calls to retrievers in a Retrieval Augmented Generation use case.::
+
+      session.get_spans_dataframe("span_kind == 'RETRIEVER'")

api_reference/source/conf.py

@@ -146,16 +146,7 @@ def setup(app):
 # If READTHEDOCS_VERSION doesn't exist, we're not on RTD
 # If it is an integer, we're in a PR build and the version isn't correct.
 # If it's "latest" → change to "dev" (that's what we want the switcher to call it)
-if not version_match or version_match.isdigit() or version_match == "latest":
-    # For local development, infer the version to match from the package.
-    if "dev" in release or "rc" in release:
-        version_match = "dev"
-        # We want to keep the relative reference if we are in dev mode
-        # but we want the whole url if we are effectively in a released version
-        json_url = "_static/switcher.json"
-    else:
-        version_match = f"v{release}"
-elif version_match == "stable":
+if not version_match or version_match.isdigit() or version_match == "stable":
     version_match = f"v{release}"
 
 # -- Options for HTML output -------------------------------------------------
@@ -194,13 +185,13 @@ def setup(app):
     "navbar_start": ["navbar-logo", "version-switcher"],
     "switcher": {
         "json_url": json_url,
-        "version_match": release,
+        "version_match": version_match,
     },
     "secondary_sidebar_items": [],
     "footer_start": [],
     "footer_end": ["copyright"],
     "navigation_depth": 3,
-    "collapse_navigation": True
+    "collapse_navigation": True,
 }
 
 html_sidebars = {