langfuse · jannikmaierhoefer · Sep 4, 2026 · Sep 4, 2026 · Sep 4, 2026 · Sep 4, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -154,9 +154,11 @@ If you change CI bootstrap:
 
 ```bash
 uv build --no-sources
-uv run --group docs pdoc -o docs/ --docformat google --logo "https://langfuse.com/langfuse_logo.svg" langfuse
+bash scripts/build_reference_docs.sh
 ```
 
+Build the reference through that script, not by calling pdoc directly -- it applies the `pdoc-templates/` overrides and the 404 page that the hosted site needs. See "SDK Reference" in `CONTRIBUTING.md`.
+
 Releases are handled by GitHub Actions. Do not build an ad hoc local release flow into repository instructions.
 
 ## External Docs

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -125,18 +125,18 @@ The workflow will automatically:
 
 Note: The generated SDK reference is currently work in progress.
 
-The SDK reference is generated via pdoc. The docs dependency group is installed on demand when you run the documentation commands.
+The SDK reference is generated via pdoc and published at [python.reference.langfuse.com](https://python.reference.langfuse.com). The docs dependency group is installed on demand when you run the documentation commands.
 
-To update the reference, run the following command:
+To build the reference into `docs/`, run:
 
 ```sh
-uv run --group docs pdoc -o docs/ --docformat google --logo "https://langfuse.com/langfuse_logo.svg" langfuse
+bash scripts/build_reference_docs.sh
 ```
 
-To run the reference locally, you can use the following command:
+To browse the reference locally with live reload, run pdoc's dev server:
 
 ```sh
-uv run --group docs pdoc --docformat google --logo "https://langfuse.com/langfuse_logo.svg" langfuse
+uv run --group docs pdoc --docformat google --logo "https://langfuse.com/langfuse_logo.svg" --template-directory pdoc-templates langfuse
 ```
 
 ## Credits

diff --git a/pdoc-templates/404.html b/pdoc-templates/404.html
@@ -0,0 +1,63 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex" />
+    <title>Page not found &ndash; Langfuse Python SDK API reference</title>
+    <style>
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        font-family:
+          system-ui,
+          -apple-system,
+          "Segoe UI",
+          Roboto,
+          "Helvetica Neue",
+          Arial,
+          sans-serif;
+        color: #212529;
+        background: #fff;
+      }
+      main {
+        max-width: 32rem;
+        padding: 2rem;
+        text-align: center;
+      }
+      img {
+        max-width: 12rem;
+        margin-bottom: 2rem;
+      }
+      h1 {
+        font-size: 1.5rem;
+        margin: 0 0 0.75rem;
+      }
+      p {
+        margin: 0 0 1.5rem;
+        line-height: 1.6;
+        color: #495057;
+      }
+      a {
+        color: #0d6efd;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <img src="https://langfuse.com/langfuse_logo.svg" alt="Langfuse" />
+      <h1>Page not found</h1>
+      <p>
+        This page is not part of the Langfuse Python SDK API reference. The
+        symbol may have been renamed or removed in a later release.
+      </p>
+      <p>
+        <a href="/">Browse the API reference</a> &middot;
+        <a href="https://langfuse.com/docs">Langfuse documentation</a>
+      </p>
+    </main>
+  </body>
+</html>
diff --git a/pdoc-templates/index.html.jinja2 b/pdoc-templates/index.html.jinja2
@@ -0,0 +1,70 @@
+{#
+Root page of https://python.reference.langfuse.com.
+
+pdoc's default index is a bare `<meta http-equiv="refresh">` stub with no
+title, no links and no canonical URL, because a single root module makes
+`langfuse.html` the entry point. Search engines read that stub as a
+soft-redirecting duplicate of `/index.html`. Setting `root_module_name` to
+false -- the escape hatch the default template documents -- renders the real
+module list instead, and the `content` block below gives that page something
+to say, since pdoc's own version leaves the main column empty.
+#}
+{% set canonical_base_url = env.get("PDOC_CANONICAL_BASE_URL", "https://python.reference.langfuse.com/").rstrip("/") ~ "/" %}
+{% set root_module_name = false %}
+{% extends "default/index.html.jinja2" %}
+
+{% block title %}Langfuse Python SDK API reference{% endblock %}
+
+{% block head %}
+    <link rel="canonical" href="{{ canonical_base_url }}"/>
+    <meta name="description"
+          content="Generated API reference for the Langfuse Python SDK: clients, tracing, prompt management, datasets, evaluation and the underlying API models."/>
+{% endblock %}
+
+{% block content %}
+    <header class="pdoc">
+        {{ self.logo() }}
+        {% if search %}
+            <input type="search" placeholder="Search API Documentation..." aria-label="search box">
+        {% endif %}
+    </header>
+    <main class="pdoc">
+        <section>
+            <h1>Langfuse Python SDK API reference</h1>
+            <p>
+                Generated reference for the <code>langfuse</code> package. It documents
+                every public symbol; the hand-written guides on
+                <a href="https://langfuse.com/docs">langfuse.com/docs</a> are the better
+                starting point if you are setting Langfuse up for the first time.
+            </p>
+            <h2>Start here</h2>
+            {#
+            These keep the `.html` suffix even though the hosted site serves
+            clean URLs. pdoc generates its own sidebar links that way, and
+            extensionless paths 404 both under pdoc's dev server and when the
+            built output is served locally, so the one 308 hop in production is
+            the cheaper trade. Canonical URLs are a different case -- those must
+            not point at a redirect, which is why they drop the suffix.
+            #}
+            <ul>
+                <li><a href="langfuse.html"><code>langfuse</code></a> &mdash; the
+                    <code>Langfuse</code> client, tracing decorators and context helpers.
+                    Most code only needs this module.</li>
+                <li><a href="langfuse/experiment.html"><code>langfuse.experiment</code></a>
+                    &mdash; running experiments over datasets and scoring the results.</li>
+                <li><a href="langfuse/api.html"><code>langfuse.api</code></a> &mdash; the
+                    generated low-level API client and its request and response models.</li>
+            </ul>
+            <h2>Elsewhere</h2>
+            <ul>
+                <li><a href="https://langfuse.com/docs/observability/sdk/python/overview">Python SDK documentation</a></li>
+                <li><a href="https://github.com/langfuse/langfuse-python">langfuse-python on GitHub</a></li>
+                <li><a href="https://pypi.org/project/langfuse/">langfuse on PyPI</a></li>
+            </ul>
+            <p>Every module is listed in the sidebar, and the search box covers all of them.</p>
+        </section>
+    </main>
+    {% if search %}
+        {% include "search.html.jinja2" %}
+    {% endif %}
+{% endblock %}
diff --git a/pdoc-templates/module.html.jinja2 b/pdoc-templates/module.html.jinja2
@@ -0,0 +1,15 @@
+{#
+Adds a self-referencing canonical URL to every module page.
+
+The `.html` suffix is deliberately dropped: Cloudflare Pages serves this site
+with clean URLs and 308-redirects `/langfuse.html` to `/langfuse`, so a
+canonical pointing at the `.html` path would point at a redirect.
+#}
+{% set canonical_base_url = env.get("PDOC_CANONICAL_BASE_URL", "https://python.reference.langfuse.com/").rstrip("/") ~ "/" %}
+{% extends "default/module.html.jinja2" %}
+
+{% block head %}
+    {{ super() }}
+    <link rel="canonical"
+          href="{{ canonical_base_url }}{{ module.modulename.replace('.', '/') }}"/>
+{% endblock %}
diff --git a/scripts/build_reference_docs.sh b/scripts/build_reference_docs.sh
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Builds the API reference published at https://python.reference.langfuse.com.
+#
+# Use this instead of calling pdoc directly: it applies the template overrides
+# in pdoc-templates/ and ships the 404 page, both of which the hosted site
+# needs. Set PDOC_CANONICAL_BASE_URL to build for a different origin.
+set -euo pipefail
+
+OUT_DIR="${1:-docs}"
+
+# Resolve a relative output path against the caller's working directory before
+# cd'ing to the repo root, so `build_reference_docs.sh out` from elsewhere does
+# not silently write to <repo>/out.
+case "$OUT_DIR" in
+  /*) ;;
+  *) OUT_DIR="$PWD/$OUT_DIR" ;;
+esac
+
+cd "$(dirname "$0")/.."
+
+uv run --group docs pdoc \
+  -o "$OUT_DIR" \
+  --docformat google \
+  --logo "https://langfuse.com/langfuse_logo.svg" \
+  --logo-link "https://langfuse.com" \
+  --template-directory pdoc-templates \
+  --edit-url "langfuse=https://github.com/langfuse/langfuse-python/blob/main/langfuse/" \
+  --no-show-source \
+  langfuse
+
+# Cloudflare Pages serves the closest index.html with a 200 for any unmatched
+# path unless the output contains a 404.html, which turns every stale or
+# mistyped URL into an indexable duplicate of the landing page.
+cp pdoc-templates/404.html "$OUT_DIR/404.html"
+
+echo "Reference docs written to $OUT_DIR/"