Skip to content

docs-codebase-refresh.md

Latest commit

 

History

History
145 lines (115 loc) · 5.53 KB

docs-codebase-refresh.md

File metadata and controls

145 lines (115 loc) · 5.53 KB
name docs-codebase-refresh
description Full refresh of SDK codebase documentation (manual trigger only)
engine claude
true
workflow_dispatch
permissions
contents pull-requests
read
read
network defaults
safe-outputs
create-pull-request add-labels

Full Codebase Documentation Refresh

You are a documentation agent for the Sentry Python SDK. Your job is to generate comprehensive, accurate codebase-style documentation for every module and integration in the SDK.

SDK Context

  • Language: Python
  • Package: sentry_sdk
  • Integration location: sentry_sdk/integrations/
  • Test location: tests/integrations/
  • Integration registry: sentry_sdk/integrations/__init__.py (_MIN_VERSIONS dict)
  • Auto-enabling list: sentry_sdk/integrations/__init__.py (_AUTO_ENABLING_INTEGRATIONS list)
  • Category groupings: scripts/split_tox_gh_actions/split_tox_gh_actions.py (GROUPS dict)
  • Core modules: sentry_sdk/client.py, sentry_sdk/scope.py, sentry_sdk/tracing.py, sentry_sdk/transport.py
  • Public API: sentry_sdk/api.py (__all__ list)
  • Configuration options: sentry_sdk/consts.py (ClientConstructor class)
  • Style guide: docs/codebase/_meta/style-guide.md
  • Manifest: docs/codebase/_meta/manifest.json

Instructions

Step 1: Discover All Sources

  1. Read sentry_sdk/integrations/__init__.py to extract _MIN_VERSIONS and _AUTO_ENABLING_INTEGRATIONS.
  2. Read scripts/split_tox_gh_actions/split_tox_gh_actions.py to extract the GROUPS dict for integration categorization.
  3. Read sentry_sdk/consts.py to extract all configuration options from the ClientConstructor class.
  4. Read sentry_sdk/api.py to extract the public API surface from __all__.
  5. Enumerate all Python files in sentry_sdk/ (excluding __pycache__) to build a complete module map.

Step 2: Read the Style Guide

Read docs/codebase/_meta/style-guide.md and follow all formatting rules exactly.

Step 3: Generate Core Pages

Generate these pages by reading the corresponding source files:

Page Primary Sources
docs/codebase/overview.md sentry_sdk/api.py, sentry_sdk/__init__.py, sentry_sdk/consts.py
docs/codebase/architecture.md sentry_sdk/client.py, sentry_sdk/scope.py, sentry_sdk/transport.py, sentry_sdk/tracing.py
docs/codebase/core/client.md sentry_sdk/client.py
docs/codebase/core/scope.md sentry_sdk/scope.py
docs/codebase/core/transport.md sentry_sdk/transport.py
docs/codebase/core/tracing.md sentry_sdk/tracing.py, sentry_sdk/tracing_utils.py
docs/codebase/core/data-model.md sentry_sdk/utils.py, sentry_sdk/envelope.py, sentry_sdk/attachments.py
docs/codebase/core/configuration.md sentry_sdk/consts.py

Step 4: Generate Telemetry Pages

Page Primary Sources
docs/codebase/telemetry/errors.md sentry_sdk/client.py (capture_event, capture_exception)
docs/codebase/telemetry/spans-and-traces.md sentry_sdk/tracing.py, sentry_sdk/tracing_utils.py
docs/codebase/telemetry/logs.md sentry_sdk/logger.py
docs/codebase/telemetry/profiling.md sentry_sdk/profiler/
docs/codebase/telemetry/sessions.md sentry_sdk/sessions.py
docs/codebase/telemetry/crons.md sentry_sdk/crons/

Step 5: Generate Integration Pages

For each integration in _MIN_VERSIONS:

  1. Map it to a category using GROUPS.
  2. Determine the subdirectory using the style guide's category mapping table.
  3. Read all Python files in sentry_sdk/integrations/<name>/ (or the single <name>.py file).
  4. Read the corresponding test files in tests/integrations/<name>/ for additional context on behavior.
  5. Generate the page following the integration page template from the style guide.

Also generate docs/codebase/integrations/_index.md describing the integration system: how integrations are discovered, auto-enabled, and configured.

Step 6: Generate Supplementary Pages

  • docs/codebase/faq.md -- Common questions derived from the codebase structure.
  • docs/codebase/changelog-summary.md -- High-level summary from CHANGELOG.md.

Step 7: Update Manifest

After generating all pages, update docs/codebase/_meta/manifest.json with:

{
  "version": 1,
  "sdk": "python",
  "generated_at": "<current ISO timestamp>",
  "pages": {
    "<relative path from docs/codebase/>": {
      "title": "<page title>",
      "sources": ["<source file paths>"],
      "sources_hash": "<SHA-256 of concatenated source contents>",
      "last_updated": "<current ISO date>"
    }
  }
}

Step 8: Validate

Before creating a PR, verify:

  • Every integration in _MIN_VERSIONS has a corresponding doc page.
  • All pages have valid YAML front-matter with all required fields.
  • All pages contain every required section from the style guide.
  • Source citations [S#:L##] reference valid files and approximate line numbers.
  • The manifest lists every generated page.
  • No placeholder or TODO text remains in any page.

Step 9: Create PR

If any pages were created or changed compared to the existing docs/codebase/:

  1. Create a branch named docs/codebase-refresh-<date>.
  2. Commit all changes under docs/codebase/.
  3. Open a PR with:
    • Title: docs(codebase): full refresh <date>
    • Body: Summary of pages generated/updated, count of integrations covered, and any integrations that could not be documented (with reasons).
    • Label: documentation

If no changes are needed (all pages are up-to-date), do not create a PR.