diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b950efd1ff..62050885f0 100644 --- a/.github/workflows/ci.yml +++ b/.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 }} diff --git a/Makefile b/Makefile index d10bd36c88..4a7c89b2a9 100644 --- a/Makefile +++ b/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 diff --git a/docs/api/agent.md b/docs/api/agent.md index fe2f6e02b7..2152da3808 100644 --- a/docs/api/agent.md +++ b/docs/api/agent.md @@ -19,5 +19,3 @@ options: members: - KnownModelName - - ResultValidatorFunc - - SystemPromptFunc diff --git a/docs/api/models/index.md b/docs/api/models/base.md similarity index 100% rename from docs/api/models/index.md rename to docs/api/models/base.md diff --git a/docs/api/result.md b/docs/api/result.md index 477509b61f..83d61af813 100644 --- a/docs/api/result.md +++ b/docs/api/result.md @@ -2,9 +2,9 @@ ::: pydantic_ai.result options: + inherited_members: true members: - ResultData - RunResult - StreamedRunResult - - _BaseRunResult - Cost diff --git a/docs/index.md b/docs/index.md index 49854e19d1..d5cb58130c 100644 --- a/docs/index.md +++ b/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). diff --git a/mkdocs.yml b/mkdocs.yml index a4e5c51aa7..507102e28a 100644 --- a/mkdocs.yml +++ b/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 diff --git a/pydantic_ai/result.py b/pydantic_ai/result.py index 84c5183415..ee6de72b77 100644 --- a/pydantic_ai/result.py +++ b/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.""" diff --git a/pyproject.toml b/pyproject.toml index ae0c96f8d8..791a7574f7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -72,7 +72,6 @@ docs = [ "mkdocs", "mkdocs-material", "mkdocstrings-python", - "griffe", ] [tool.hatch.build.targets.wheel] diff --git a/uv.lock b/uv.lock index cd48588dcd..63b9160607 100644 --- a/uv.lock +++ b/uv.lock @@ -1243,7 +1243,6 @@ dev = [ { name = "ruff" }, ] docs = [ - { name = "griffe" }, { name = "mkdocs" }, { name = "mkdocs-material" }, { name = "mkdocstrings-python" }, @@ -1280,7 +1279,6 @@ dev = [ { name = "ruff", specifier = ">=0.6.9" }, ] docs = [ - { name = "griffe" }, { name = "mkdocs" }, { name = "mkdocs-material" }, { name = "mkdocstrings-python" },