docs: review documentation updates for c11d3a737

[github-actions]

Documentation Update Review

Triggered by commit: c11d3a737
Generated: 2026-04-30 20:42 UTC
Compare: 4f756763caa25541ecd6a59937cdc893aa898fe2...c11d3a737

Affected Documents

Document	Files Changed	Status
DVC Setup Guide	1 file	✅ Reviewed
Installation Guide	1 file	✅ Reviewed

All Changed Files in This Commit

Click to expand

pychron/core/tests/bridge_client_test.py
pychron/core/tests/bridge_host_test.py
pychron/core/tests/dvc_make_url_hook_test.py
pychron/dvc/dvc.py
pychron/envisage/pychron_run.py
pychron/git/hosts/_bridge_client.py
pychron/git/hosts/bridge.py
pychron/git/tasks/bridge_plugin.py
pychron/git/tasks/bridge_preferences.py
pyproject.toml

---

DVC Setup Guide {#dvc-setup-guide}

Doc file: docs/dvc_setup_guide.md
Matched prefixes: pychron/dvc/

Changed Files

• pychron/dvc/dvc.py

AI Review

Code Change Summary

The code adds a new "Pychron Forgejo Bridge" service that takes priority over the existing GitHub/GitLab git hosting services when making repository URLs. This introduces a new component in the DVC architecture that can override the standard git host resolution, with fallback behavior to the legacy services when the bridge fails or returns empty URLs.

Documentation Updates Required

• Section/Topic: Storage layers / DVC architecture overview
  Issue: The documentation likely describes only GitHub/GitLab as git hosting options, but now there's a Bridge service that can take priority
  Suggested update: Add explanation that a "Pychron Forgejo Bridge" service can be registered and enabled to override standard git host URL resolution, with automatic fallback to GitHub/GitLab when the bridge is unavailable or returns no URL

• Section/Topic: Configuration fields and preferences
  Issue: Missing documentation for Bridge service configuration options
  Suggested update: Document the Bridge service configuration fields including how to enable it ("enabled" property) and any setup requirements for the Bridge to properly resolve repository URLs

• Section/Topic: Failure modes section
  Issue: New failure mode not documented - what happens when Bridge is enabled but fails
  Suggested update: Add failure mode describing Bridge service fallback behavior: when Bridge returns empty URL or fails, system automatically falls back to configured GitHub/GitLab service with a warning logged

• Section/Topic: Initialization and first-run sequence
  Issue: The service registration and priority handling for Bridge vs standard git hosts is not covered
  Suggested update: Explain that during DVC initialization, if multiple IGitHost services are registered, the Bridge service (when enabled) takes priority over GitHub/GitLab services for URL resolution

---

Installation Guide {#installation-guide}

Doc file: docs/installation_guide.md
Matched prefixes: pyproject.toml, app_utils/, uv.lock

Changed Files

• pyproject.toml

AI Review

Code Change Summary

A new dependency google-auth>=2.30.0,<3 has been added to the core dependencies list in pyproject.toml. This is a significant addition as it introduces Google authentication capabilities as a required dependency for all Pychron installations, which may affect installation requirements, system dependencies, or authentication workflows that users need to be aware of.

Documentation Updates Required

• Section/Topic: Dependencies or Requirements section
  Issue: The installation guide may not mention the new google-auth dependency and any system-level requirements it might have
  Suggested update: Add google-auth to the list of core dependencies and document any additional system requirements (such as specific SSL/TLS libraries) that may be needed for Google authentication to work properly

• Section/Topic: Authentication or Configuration section
  Issue: The addition of google-auth as a core dependency suggests new authentication capabilities that may require user configuration
  Suggested update: Document any new environment variables, configuration files, or setup steps required for Google authentication integration, including how this relates to the existing PYCHRON_USE_LOGIN environment variable

• Section/Topic: Troubleshooting or Platform-specific notes
  Issue: Google authentication libraries may have platform-specific installation or runtime requirements that could cause issues
  Suggested update: Add troubleshooting guidance for common google-auth related installation issues, particularly on different platforms (macOS, Linux, Windows) where SSL certificate handling or system authentication libraries might differ

---

This file was auto-generated by scripts/doc_audit.py. A human must review and apply any changes to the documentation.