From 71944c595a1a5d6d475f5e365bec722eb5333aa2 Mon Sep 17 00:00:00 2001
From: "Ilya (Marshal)" <ilya@marshal.dev>
Date: Sat, 24 Oct 2026 17:52:45 +0200
Subject: [PATCH] Add page descriptions for search results and link previews

---
 docs/source/api/index.md                |  4 ++++
 docs/source/benchmarks.md               |  4 +---
 docs/source/change_log.md               |  4 ++++
 docs/source/conf.py                     | 20 +++++++++++++++++++-
 docs/source/examples/browser_server.md  |  4 ++++
 docs/source/examples/echo.md            |  4 ++++
 docs/source/examples/gemini_live.md     |  4 ++++
 docs/source/examples/index.md           |  4 ++++
 docs/source/examples/janus_streaming.md |  4 ++++
 docs/source/examples/openai_live.md     |  4 ++++
 docs/source/examples/recorder.md        |  4 ++++
 docs/source/examples/whip_whep.md       |  4 ++++
 docs/source/guides/aiortc.md            |  4 ++++
 docs/source/guides/connections.md       |  4 ++++
 docs/source/guides/data-channels.md     |  4 ++++
 docs/source/guides/events.md            |  4 ++++
 docs/source/guides/field-trials.md      |  4 ++++
 docs/source/guides/h264.md              |  4 ++++
 docs/source/guides/index.md             |  4 ++++
 docs/source/guides/media.md             |  4 ++++
 docs/source/index.md                    |  4 +---
 docs/source/licence.md                  |  4 ++++
 docs/source/quickstart.md               |  4 ++++
 docs/source/security.md                 |  4 ++++
 24 files changed, 105 insertions(+), 7 deletions(-)

diff --git a/docs/source/api/index.md b/docs/source/api/index.md
index fa0f37a..a27e683 100644
--- a/docs/source/api/index.md
+++ b/docs/source/api/index.md
@@ -1,3 +1,7 @@
+---
+description: "The Python WebRTC API reference: RTCPeerConnection, data channels, tracks, streams, events, enums and exceptions, as in the W3C specifications."
+---
+
 # API reference
 
 Everything is importable from the package itself: `webrtc.RTCPeerConnection`, `webrtc.RTCConfiguration`,
diff --git a/docs/source/benchmarks.md b/docs/source/benchmarks.md
index 4dd70f8..7dc3f31 100644
--- a/docs/source/benchmarks.md
+++ b/docs/source/benchmarks.md
@@ -1,7 +1,5 @@
 ---
-myst:
-  html_meta:
-    "description": "Python WebRTC against aiortc, Pion, libdatachannel and webrtc-rs: connection setup, data channels, memory and media"
+description: "Python WebRTC against aiortc, Pion, libdatachannel and webrtc-rs: connection setup, data channels, memory and media"
 ---
 
 # Benchmarks
diff --git a/docs/source/change_log.md b/docs/source/change_log.md
index 8b1749d..a847e8d 100644
--- a/docs/source/change_log.md
+++ b/docs/source/change_log.md
@@ -1,2 +1,6 @@
+---
+description: "What changed in each release of Python WebRTC, the wrtc package on PyPI."
+---
+
 ```{include} ../../CHANGES.md
 ```
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 0ef27a8..b80597b 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -11,11 +11,12 @@
 
 import ast
 import enum
+import html
 import inspect
 import os
 import sys
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from docutils import nodes
 from pygments.formatters import HtmlFormatter
@@ -384,6 +385,21 @@ def scope_pygments_to_theme(app: Sphinx, exception: Exception | None) -> None:
     (Path(app.outdir) / '_static' / 'pygments.css').write_text('\n'.join(blocks), encoding='UTF-8')
 
 
+def use_page_description(
+    _app: Sphinx, _pagename: str, _templatename: str, context: dict[str, Any], _doctree: nodes.document | None
+) -> None:
+    """Give search results and link previews the ``description`` of the page's front matter.
+
+    Without it, OpenGraph cuts both from the first paragraph of the page.
+    """
+    description = (context.get('meta') or {}).get('description')
+    if not description:
+        return
+
+    context['meta']['og:description'] = description
+    context['metatags'] += f'<meta name="description" content="{html.escape(description)}" />\n'
+
+
 def _design_components(root: nodes.Element, component: str) -> list[nodes.container]:
     return [node for node in root.findall(nodes.container) if node.get('design_component') == component]
 
@@ -433,3 +449,5 @@ def setup(app: Sphinx) -> None:
     app.connect('autodoc-process-signature', hide_enum_signatures)
     app.connect('env-check-consistency', register_short_aliases)
     app.connect('build-finished', scope_pygments_to_theme)
+    # before OpenGraph, which connects at the default priority
+    app.connect('html-page-context', use_page_description, priority=400)
diff --git a/docs/source/examples/browser_server.md b/docs/source/examples/browser_server.md
index b491bac..4aa2671 100644
--- a/docs/source/examples/browser_server.md
+++ b/docs/source/examples/browser_server.md
@@ -1,3 +1,7 @@
+---
+description: "A Python WebRTC server for a browser page: your camera comes back in grayscale, and Python answers a chat over a data channel."
+---
+
 # Browser and Python server
 
 A browser page sends your camera to Python, which sends it back in grayscale, and Python answers a chat over a data
diff --git a/docs/source/examples/echo.md b/docs/source/examples/echo.md
index a5e176f..b11b696 100644
--- a/docs/source/examples/echo.md
+++ b/docs/source/examples/echo.md
@@ -1,3 +1,7 @@
+---
+description: "A Python WebRTC peer that sends back the video it receives in grayscale, through a transform stream, as in a browser."
+---
+
 # Echo peer
 
 Sends back the video it receives, in grayscale. A processor is piped through a transform stream into a generator,
diff --git a/docs/source/examples/gemini_live.md b/docs/source/examples/gemini_live.md
index b6358fb..8a87ff5 100644
--- a/docs/source/examples/gemini_live.md
+++ b/docs/source/examples/gemini_live.md
@@ -1,3 +1,7 @@
+---
+description: "A Gemini Live voice agent in the browser with live transcripts, through a Python WebRTC server that keeps the API key."
+---
+
 # Voice agent with Gemini Live
 
 Talks to Gemini from a browser page, with live transcripts, through a Python server in the middle:
diff --git a/docs/source/examples/index.md b/docs/source/examples/index.md
index c2b3d38..04615d5 100644
--- a/docs/source/examples/index.md
+++ b/docs/source/examples/index.md
@@ -1,3 +1,7 @@
+---
+description: "Complete Python WebRTC programs: a server for a browser page, voice agents, WHIP and WHEP, live streams in the terminal and more."
+---
+
 # Examples
 
 Complete programs from the [examples](https://github.com/MarshalX/python-webrtc/tree/main/examples) directory of the
diff --git a/docs/source/examples/janus_streaming.md b/docs/source/examples/janus_streaming.md
index d38f9b1..9a7e7e0 100644
--- a/docs/source/examples/janus_streaming.md
+++ b/docs/source/examples/janus_streaming.md
@@ -1,3 +1,7 @@
+---
+description: "Play a live WebRTC stream in the terminal with Python: the video as colored characters, the audio on your speakers."
+---
+
 # Live stream in the terminal
 
 Plays a stream of the public [Janus](https://janus.conf.meetecho.com/) demo server. The video is drawn with colored
diff --git a/docs/source/examples/openai_live.md b/docs/source/examples/openai_live.md
index 288edd0..046b063 100644
--- a/docs/source/examples/openai_live.md
+++ b/docs/source/examples/openai_live.md
@@ -1,3 +1,7 @@
+---
+description: "Talk to OpenAI GPT-Live from Python over WebRTC, with your microphone, speakers and live transcripts in the terminal."
+---
+
 # Voice chat with OpenAI GPT-Live
 
 Talks to the model through your microphone and speakers, with live transcripts in the terminal. It needs no server, only an
diff --git a/docs/source/examples/recorder.md b/docs/source/examples/recorder.md
index e922263..92c5d15 100644
--- a/docs/source/examples/recorder.md
+++ b/docs/source/examples/recorder.md
@@ -1,3 +1,7 @@
+---
+description: "Record the video and audio a Python WebRTC peer receives to raw I420 and PCM files."
+---
+
 # Recorder
 
 Writes the video and audio a peer receives to raw I420 and PCM files, with {obj}`~webrtc.MediaStreamTrackProcessor`.
diff --git a/docs/source/examples/whip_whep.md b/docs/source/examples/whip_whep.md
index ed8e082..61f5a66 100644
--- a/docs/source/examples/whip_whep.md
+++ b/docs/source/examples/whip_whep.md
@@ -1,3 +1,7 @@
+---
+description: "Play a live stream over WHEP in the terminal, or publish one over WHIP, with Python WebRTC."
+---
+
 # WHIP and WHEP
 
 Plays a live stream over [WHEP](https://www.rfc-editor.org/rfc/rfc9725) in the terminal, or publishes one over WHIP.
diff --git a/docs/source/guides/aiortc.md b/docs/source/guides/aiortc.md
index f133753..4175fc6 100644
--- a/docs/source/guides/aiortc.md
+++ b/docs/source/guides/aiortc.md
@@ -1,3 +1,7 @@
+---
+description: "Run aiortc code on Chrome's WebRTC engine: install wrtc[aiortc], change the imports to webrtc.aiortc, and the rest stays as it is."
+---
+
 # Migrating from aiortc
 
 `webrtc.aiortc` runs code written for aiortc 1.15 on Python WebRTC's engine. Install the extra, change the imports,
diff --git a/docs/source/guides/connections.md b/docs/source/guides/connections.md
index 8ae7887..0e987ed 100644
--- a/docs/source/guides/connections.md
+++ b/docs/source/guides/connections.md
@@ -1,3 +1,7 @@
+---
+description: "Create an RTCPeerConnection in Python, exchange SDP and ICE candidates over your signalling, and follow its states and stats."
+---
+
 # Connections
 
 {obj}`~webrtc.RTCPeerConnection` is one end of a connection. Each end describes itself in an SDP description, and
diff --git a/docs/source/guides/data-channels.md b/docs/source/guides/data-channels.md
index 554d07f..0d21d42 100644
--- a/docs/source/guides/data-channels.md
+++ b/docs/source/guides/data-channels.md
@@ -1,3 +1,7 @@
+---
+description: "Send text and binary messages between peers with RTCDataChannel in Python: opening, options, back pressure and closing."
+---
+
 # Data channels
 
 An {obj}`~webrtc.RTCDataChannel` sends messages between the peers, over SCTP inside the encrypted connection. See {mdn}`RTCDataChannel`.
diff --git a/docs/source/guides/events.md b/docs/source/guides/events.md
index 0f09b1e..edd5247 100644
--- a/docs/source/guides/events.md
+++ b/docs/source/guides/events.md
@@ -1,3 +1,7 @@
+---
+description: "Listen to the events of WebRTC connections, channels and tracks in Python: handlers, one-shot handlers, removal and errors."
+---
+
 # Events
 
 Connections, channels, tracks and transports fire the events of the specification. Every one of them is an
diff --git a/docs/source/guides/field-trials.md b/docs/source/guides/field-trials.md
index 994db21..8bc7f91 100644
--- a/docs/source/guides/field-trials.md
+++ b/docs/source/guides/field-trials.md
@@ -1,3 +1,7 @@
+---
+description: "Turn on features the native WebRTC engine ships turned off, such as WARP, with webrtc.field_trials in Python."
+---
+
 # Field trials
 
 The native WebRTC engine ships some features turned off, behind field trials. A trial has a name, like
diff --git a/docs/source/guides/h264.md b/docs/source/guides/h264.md
index 879a480..b40d859 100644
--- a/docs/source/guides/h264.md
+++ b/docs/source/guides/h264.md
@@ -1,3 +1,7 @@
+---
+description: "H.264 in Python WebRTC: VideoToolbox on macOS, and Cisco's OpenH264 binary downloaded at runtime elsewhere."
+---
+
 # H.264
 
 On macOS, H.264 comes from the OS's VideoToolbox and is always offered: Constrained Baseline and High, sent and
diff --git a/docs/source/guides/index.md b/docs/source/guides/index.md
index 80b53bf..11bed38 100644
--- a/docs/source/guides/index.md
+++ b/docs/source/guides/index.md
@@ -1,3 +1,7 @@
+---
+description: "Guides to Python WebRTC: connections, data channels, media, events, H.264, field trials and migrating from aiortc."
+---
+
 # Guides
 
 The API is the one of the browsers, so the guides of MDN apply as they are, in snake_case. These pages cover what
diff --git a/docs/source/guides/media.md b/docs/source/guides/media.md
index 260acd7..751f5ff 100644
--- a/docs/source/guides/media.md
+++ b/docs/source/guides/media.md
@@ -1,3 +1,7 @@
+---
+description: "Receive, send and transform audio and video in Python with MediaStreamTrackProcessor and MediaStreamTrackGenerator, as in a browser."
+---
+
 # Media
 
 Media is read from tracks and written to them with the APIs of the browsers:
diff --git a/docs/source/index.md b/docs/source/index.md
index b952a97..b8ebffc 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -1,7 +1,5 @@
 ---
-myst:
-  html_meta:
-    "description": "Python WebRTC: Chrome's WebRTC engine, with the browser API, in Python"
+description: "Chrome's WebRTC engine with the browser API, in Python: peer connections, data channels, audio and video. Prebuilt wheels for Linux, macOS and Windows."
 ---
 
 # Python WebRTC
diff --git a/docs/source/licence.md b/docs/source/licence.md
index ce38b34..8e14923 100644
--- a/docs/source/licence.md
+++ b/docs/source/licence.md
@@ -1,3 +1,7 @@
+---
+description: "Python WebRTC is under the BSD 3-Clause License. The licences of the bundled third-party code are listed too."
+---
+
 # Licence
 
 BSD 3-Clause License. File in repository: [LICENSE.md](https://github.com/MarshalX/python-webrtc/blob/main/LICENSE.md)
diff --git a/docs/source/quickstart.md b/docs/source/quickstart.md
index 0b2fc32..c75499a 100644
--- a/docs/source/quickstart.md
+++ b/docs/source/quickstart.md
@@ -1,3 +1,7 @@
+---
+description: "Install wrtc from PyPI and connect two Python peers over a WebRTC data channel in a few lines."
+---
+
 # Quickstart
 
 ## Installation
diff --git a/docs/source/security.md b/docs/source/security.md
index ff2e944..fd65582 100644
--- a/docs/source/security.md
+++ b/docs/source/security.md
@@ -1,2 +1,6 @@
+---
+description: "Which versions of Python WebRTC get security fixes, and how to report a vulnerability."
+---
+
 ```{include} ../../SECURITY.md
 ```