Fix source locations in documentation for external packages (pydantic#11710)

Co-authored-by: Stephen McDowell <[email protected]>

Author: Viicos

.github/workflows/ci.yml

@@ -56,17 +56,14 @@ jobs:
 
     - run: uv run python -c 'import docs.plugins.main'
 
-    # Adding local symlinks gets nice source locations like
-    #   pydantic_core/core_schema.py
-    # instead of
-    #   .venv/lib/python3.10/site-packages/pydantic_core/core_schema.py
+    # Taken from docs-build.sh
     - name: prepare shortcuts for extra modules
       run: |
         ln -s .venv/lib/python*/site-packages/pydantic_core pydantic_core
         ln -s .venv/lib/python*/site-packages/pydantic_settings pydantic_settings
         ln -s .venv/lib/python*/site-packages/pydantic_extra_types pydantic_extra_types
 
-    - run: uv run mkdocs build
+    - run: PYTHONPATH="$PWD${PYTHONPATH:+:${PYTHONPATH}}" uv run mkdocs build
 
   test-memray:
     name: Test memray

.github/workflows/docs-update.yml

@@ -77,10 +77,7 @@ jobs:
 
       - run: uv run python -c 'import docs.plugins.main'
 
-      # Adding local symlinks gets nice source locations like
-      #   pydantic_core/core_schema.py
-      # instead of
-      #   .venv/lib/python3.10/site-packages/pydantic_core/core_schema.py
+      # Taken from docs-build.sh
       - name: Prepare shortcuts for extra modules
         run: |
           ln -s .venv/lib/python*/site-packages/pydantic_core pydantic_core
@@ -92,7 +89,7 @@ jobs:
           git config --global user.name "${{ github.actor }}"
           git config --global user.email "${{ github.actor }}@users.noreply.github.com"
 
-      - run: uv run mike deploy -b docs-site dev --push
+      - run: PYTHONPATH="$PWD${PYTHONPATH:+:${PYTHONPATH}}" uv run mike deploy -b docs-site dev --push
         if: github.ref == 'refs/heads/main'
 
       - if: github.ref == 'refs/heads/docs-update' || startsWith(github.ref, 'refs/tags/')
@@ -102,7 +99,7 @@ jobs:
           version_file_path: 'pydantic/version.py'
           skip_env_check: true
 
-      - run: uv run mike deploy -b docs-site ${{ steps.check-version.outputs.VERSION_MAJOR_MINOR }} latest --update-aliases --push
+      - run: PYTHONPATH="$PWD${PYTHONPATH:+:${PYTHONPATH}}" uv run mike deploy -b docs-site ${{ steps.check-version.outputs.VERSION_MAJOR_MINOR }} latest --update-aliases --push
         if: ${{ (github.ref == 'refs/heads/docs-update' || startsWith(github.ref, 'refs/tags/')) && !fromJSON(steps.check-version.outputs.IS_PRERELEASE) }}
         env:
           PYDANTIC_VERSION: v${{ steps.check-version.outputs.VERSION }}

build-docs.sh

@@ -16,8 +16,10 @@ python3 -m uv run python -c 'import docs.plugins.main'
 #   pydantic_core/core_schema.py
 # instead of
 #   .venv/lib/python3.10/site-packages/pydantic_core/core_schema.py
+# See also: mkdocs.yml:mkdocstrings:handlers:python:paths: [.]:
 ln -s .venv/lib/python*/site-packages/pydantic_core pydantic_core
 ln -s .venv/lib/python*/site-packages/pydantic_settings pydantic_settings
 ln -s .venv/lib/python*/site-packages/pydantic_extra_types pydantic_extra_types
-
-python3 -m uv run --no-sync mkdocs build
+# Put these at the front of PYTHONPATH (otherwise, symlinked
+# entries will still have "Source code in .venv/lib/.../*.py ":
+PYTHONPATH="$PWD${PYTHONPATH:+:${PYTHONPATH}}" python3 -m uv run --no-sync mkdocs build

mkdocs.yml

@@ -244,7 +244,7 @@ plugins:
 - mkdocstrings:
     handlers:
       python:
-        paths: [.]
+        paths: [.]  # see also: build-docs.sh
         options:
           members_order: source
           separate_signature: true