Docs insiders (#43)

.github/workflows/ci.yml

@@ -46,7 +46,15 @@ jobs:
           enable-cache: true
 
       - run: uv sync --python 3.12 --frozen --group docs
-      - run: uv run --frozen mkdocs build
+      - run: docs
+        if: github.repository_owner != 'pydantic'
+
+      - run: make docs-insiders
+        if: github.repository_owner == 'pydantic'
+        env:
+          PPPR_TOKEN: ${{ secrets.PPPR_TOKEN }}
+
+      - run: uv pip freeze
 
   test:
     name: test on ${{ matrix.python-version }}

Makefile

@@ -67,11 +67,30 @@ docs:
 docs-serve:
 	uv run mkdocs serve --no-strict
 
+.PHONY: .docs-insiders-install # install insiders packages for docs
+.docs-insiders-install:
+	@echo 'installing insiders packages'
+	@uv pip install -U \
+		--extra-index-url https://pydantic:${PPPR_TOKEN}@pppr.pydantic.dev/simple/ \
+		mkdocs-material mkdocstrings-python
+
+.PHONY: docs-insiders  # Build the documentation using insiders packages
+docs-insiders: .docs-insiders-install
+	uv run --no-sync mkdocs build
+
+.PHONY: docs-serve-insiders  # Build and serve the documentation using insiders packages
+docs-serve-insiders: .docs-insiders-install
+	uv run --no-sync mkdocs serve
+
 .PHONY: cf-pages-build  # Install uv, install dependencies and build the docs, used on CloudFlare Pages
 cf-pages-build:
 	curl -LsSf https://astral.sh/uv/install.sh | sh
 	${HOME}/.local/bin/uv python install 3.12
 	${HOME}/.local/bin/uv sync --python 3.12 --frozen --group docs
+	${HOME}/.local/bin/uv pip install -U \
+		--extra-index-url https://pydantic:$(PPPR_TOKEN)@pppr.pydantic.dev/simple/ \
+		mkdocs-material mkdocstrings-python
+	${HOME}/.local/bin/uv pip freeze
 	${HOME}/.local/bin/uv run --no-sync mkdocs build
 
 .PHONY: all

docs/api/agent.md

@@ -19,5 +19,3 @@
     options:
       members:
         - KnownModelName
-        - ResultValidatorFunc
-        - SystemPromptFunc

docs/api/result.md

@@ -2,9 +2,9 @@
 
 ::: pydantic_ai.result
     options:
+      inherited_members: true
       members:
         - ResultData
         - RunResult
         - StreamedRunResult
-        - _BaseRunResult
         - Cost

docs/index.md

@@ -46,14 +46,14 @@ async def get_weather(
 
 async def main():
     async with httpx.AsyncClient() as client:
-    result = await weather_agent.run(
-        'What is the weather like in West London and in Wiltshire?',
-        deps=client,
-    )  # (8)!
-    print(result.data)  # (9)!
-    # > 'The weather in West London is raining, while in Wiltshire it is sunny.'
-
-    print(result.all_messages())  # (10)!
+        result = await weather_agent.run(  # (8)!
+            'What is the weather like in West London and in Wiltshire?',
+            deps=client,
+        )
+        print(result.data)  # (9)!
+        # > 'The weather in West London is raining, while in Wiltshire it is sunny.'
+
+        print(result.all_messages())  # (10)!
 ```
 
 1. An agent that can tell users about the weather in a particular location. Agents combine a system prompt, a response type (here `str`) and "retrievers" (aka tools).

mkdocs.yml

@@ -10,7 +10,7 @@ edit_uri: edit/main/docs/
 copyright: © Pydantic Services Inc. 2024 to present
 
 nav:
-  - Getting Started:
+  - Introduction:
     - index.md
     - install.md
   - API Reference:
@@ -19,12 +19,11 @@ nav:
     - api/messages.md
     - api/dependencies.md
     - api/exceptions.md
-    - "pydantic_ai.models":
-      - api/models/index.md
-      - api/models/openai.md
-      - api/models/gemini.md
-      - api/models/test.md
-      - api/models/function.md
+    - api/models/base.md
+    - api/models/openai.md
+    - api/models/gemini.md
+    - api/models/test.md
+    - api/models/function.md
 
 extra:
   # hide the "Made with Material for MkDocs" message
@@ -61,14 +60,13 @@ theme:
     - content.code.annotate
     - content.code.copy
     - content.code.select
+    - navigation.path
     - navigation.expand
     - navigation.indexes
-    - navigation.path
-    - navigation.tabs
     - navigation.sections
     - navigation.tracking
-    - navigation.top # alternatively, we could do navigation.tabs.sticky
     - toc.follow
+#    - navigation.tabs  # don't use navbar tabs
 #  logo: "logo-white.svg"
 #  favicon: "favicon.png"
 
@@ -122,6 +120,7 @@ plugins:
         python:
           paths: [src/packages/pydantic_ai/pydantic_ai]
           options:
+            relative_crossrefs: true
             members_order: source
             separate_signature: true
             show_signature_annotations: true

pydantic_ai/result.py

@@ -67,8 +67,7 @@ def __add__(self, other: Cost) -> Cost:
 class _BaseRunResult(ABC, Generic[ResultData]):
     """Base type for results.
 
-    You should not import or use this type directly, instead use its subclasses
-    [`RunResult`][pydantic_ai.result.RunResult] and [`StreamedRunResult`][pydantic_ai.result.StreamedRunResult] instead.
+    You should not import or use this type directly, instead use its subclasses `RunResult` and `StreamedRunResult`.
     """
 
     _all_messages: list[messages.Message]
@@ -80,7 +79,7 @@ def all_messages(self) -> list[messages.Message]:
         return self._all_messages
 
     def all_messages_json(self) -> bytes:
-        """Return all messages from [`all_messages`][pydantic_ai.result._BaseRunResult.all_messages] as JSON bytes."""
+        """Return all messages from [`all_messages`][..all_messages] as JSON bytes."""
         return messages.MessagesTypeAdapter.dump_json(self.all_messages())
 
     def new_messages(self) -> list[messages.Message]:
@@ -91,7 +90,7 @@ def new_messages(self) -> list[messages.Message]:
         return self.all_messages()[self._new_message_index :]
 
     def new_messages_json(self) -> bytes:
-        """Return new messages from [`new_messages`][pydantic_ai.result._BaseRunResult.new_messages] as JSON bytes."""
+        """Return new messages from [`new_messages`][..new_messages] as JSON bytes."""
         return messages.MessagesTypeAdapter.dump_json(self.new_messages())
 
     @abstractmethod
@@ -101,10 +100,7 @@ def cost(self) -> Cost:
 
 @dataclass
 class RunResult(_BaseRunResult[ResultData]):
-    """Result of a non-streamed run.
-
-    See [`_BaseRunResult`][pydantic_ai.result._BaseRunResult] for other available methods.
-    """
+    """Result of a non-streamed run."""
 
     data: ResultData
     """Data from the final response in the run."""
@@ -117,10 +113,7 @@ def cost(self) -> Cost:
 
 @dataclass
 class StreamedRunResult(_BaseRunResult[ResultData], Generic[AgentDeps, ResultData]):
-    """Result of a streamed run that returns structured data via a tool call.
-
-    See [`_BaseRunResult`][pydantic_ai.result._BaseRunResult] for other available methods.
-    """
+    """Result of a streamed run that returns structured data via a tool call."""
 
     cost_so_far: Cost
     """Cost of the run up until the last request."""

pyproject.toml

@@ -72,7 +72,6 @@ docs = [
     "mkdocs",
     "mkdocs-material",
     "mkdocstrings-python",
-    "griffe",
 ]
 
 [tool.hatch.build.targets.wheel]