Skip to content

.github-guide.md

Latest commit

 

History

History
137 lines (124 loc) · 5.29 KB

.github-guide.md

File metadata and controls

137 lines (124 loc) · 5.29 KB

Project Structure Guide

This document provides a visual overview of the SDK structure for developers.

File Tree with Edit Status

sdks/python/
│
├── 📝 README.md                    ✓ SAFE TO EDIT
├── 📝 CONTRIBUTING.md              ✓ SAFE TO EDIT  
├── 📝 DEVELOPER_QUICKREF.md        ✓ SAFE TO EDIT
├── 📝 INSTALL.md                   ✓ SAFE TO EDIT
├── 📝 SETUP_FIX.md                 ✓ SAFE TO EDIT
├── 📝 CHANGES.md                   ✓ SAFE TO EDIT
│
├── ⚙️  pyproject.toml               ✓ SAFE TO EDIT
├── ⚙️  setup.py                     ✓ SAFE TO EDIT
├── ⚙️  requirements.txt             ✓ SAFE TO EDIT
│
├── 🧪 test_install.py              ✓ SAFE TO EDIT
├── 📘 examples.py                  ✓ SAFE TO EDIT
├── 🔒 py.typed                     ✓ SAFE TO EDIT
│
├── 📋 openapi.json                 ⚠️  SOURCE OF TRUTH
│
├── 🤖 __init__.py                  ✗ GENERATED - DO NOT EDIT
├── 🤖 client.py                    ✗ GENERATED - DO NOT EDIT
├── 🤖 raw_client.py                ✗ GENERATED - DO NOT EDIT
│
├── core/                           ✗ GENERATED - DO NOT EDIT
│   ├── 🤖 __init__.py
│   ├── 🤖 http_client.py
│   ├── 🤖 client_wrapper.py
│   ├── 🤖 request_options.py
│   ├── 🤖 api_error.py
│   ├── 🤖 pydantic_utilities.py
│   └── 🤖 ...
│
├── types/                          ✗ GENERATED - DO NOT EDIT
│   ├── 🤖 __init__.py
│   ├── 🤖 message.py
│   ├── 🤖 chat_session.py
│   ├── 🤖 user_profile_response.py
│   └── 🤖 ...
│
├── errors/                         ✗ GENERATED - DO NOT EDIT
│   ├── 🤖 __init__.py
│   └── 🤖 unprocessable_entity_error.py
│
├── chat/                           ✗ GENERATED - DO NOT EDIT
│   ├── 🤖 __init__.py
│   ├── 🤖 client.py
│   └── 🤖 raw_client.py
│
├── authentication/                 ✗ GENERATED - DO NOT EDIT
│   ├── 🤖 __init__.py
│   ├── 🤖 client.py
│   └── 🤖 raw_client.py
│
├── models/                         ✗ GENERATED - DO NOT EDIT
├── providers/                      ✗ GENERATED - DO NOT EDIT
├── admin/                          ✗ GENERATED - DO NOT EDIT
├── notifications/                  ✗ GENERATED - DO NOT EDIT
├── plans/                          ✗ GENERATED - DO NOT EDIT
├── subscription/                   ✗ GENERATED - DO NOT EDIT
├── stripe_payments/                ✗ GENERATED - DO NOT EDIT
├── coupons/                        ✗ GENERATED - DO NOT EDIT
├── trial/                          ✗ GENERATED - DO NOT EDIT
├── activity/                       ✗ GENERATED - DO NOT EDIT
├── ranking/                        ✗ GENERATED - DO NOT EDIT
├── chat_history/                   ✗ GENERATED - DO NOT EDIT
└── debug/                          ✗ GENERATED - DO NOT EDIT

Legend

Symbol Meaning
📝 Documentation - safe to edit
⚙️ Configuration - safe to edit
🧪 Tests - safe to edit
📘 Examples - safe to edit
📋 API Spec - source of truth
🤖 Generated by docsalot - DO NOT EDIT

Quick Rules

✓ You CAN Edit:

  • All .md documentation files
  • pyproject.toml, setup.py, requirements.txt
  • examples.py, test_install.py
  • Any test files you create
  • .gitignore, .env files

✗ You CANNOT Edit:

  • Any file with "auto-generated by docsalot" comment
  • client.py, raw_client.py, __init__.py
  • Anything in core/, types/, errors/ directories
  • Module client files ([module]/client.py)

⚠️ To Change Generated Code:

  1. Edit openapi.json
  2. Run: docsalot generate --group python
  3. Test the regenerated code
  4. Commit both spec and generated code

Development Workflow

┌─────────────────────────────────────────┐
│  Want to change SDK behavior?           │
└─────────────────┬───────────────────────┘
                  │
        ┌─────────▼──────────┐
        │ Is it generated?   │
        └─────────┬──────────┘
                  │
        ┌─────────▼──────────┐
        │       YES          │
        │  Edit openapi.json │
        │  Regenerate SDK    │
        └────────────────────┘
                  │
        ┌─────────▼──────────┐
        │       NO           │
        │  Edit file directly│
        │  (docs, examples,  │
        │   config, etc)     │
        └────────────────────┘

See Also