# Automatic Documentation Update Guide

This guide explains the automatic documentation update system for GNS3 Copilot project using Zhipu GLM-4.5-X API.

## Overview

When you create or update a Pull Request (PR) to the `Development` branch, the automatic documentation update system will:

1. **Analyze code changes** - Detect changes in the source code
2. **Generate documentation** - Use Zhipu GLM-4.5-X AI to generate documentation updates
3. **Update documents** - Automatically update both English and Chinese documentation files
4. **Commit changes** - Submit documentation updates to your PR branch
5. **Create PR comment** - Add an English summary comment to your PR

## Configuration

### Required Secrets

Configure the following secrets in your GitHub repository:

1. Go to **Settings** → **Secrets and variables** → **Actions**
2. Click **New repository secret** and add:

| Secret Name | Value | Description |
|-------------|-------|-------------|
| `ZHIPU_API_KEY` | Your Zhipu API Key | Get from https://open.bigmodel.cn/ |
| `ZHIPU_MODEL` | `glm-4-flash` (recommended) | Fast and cost-effective model |

#### How to Get Zhipu API Key

1. Visit [Zhipu AI Open Platform](https://open.bigmodel.cn/)
2. Register or login to your account
3. Navigate to **API Key Management**
4. Create a new API key
5. Copy the key and add it to GitHub Secrets

### Required Permissions

Ensure GitHub Actions has write permissions:

1. Go to **Settings** → **Actions** → **General**
2. Under **Workflow permissions**, select:
   - ✅ **Read and write permissions**
3. Click **Save**

## Workflow

### Trigger Events

The workflow triggers on PR events:
- `opened` - New PR created
- `synchronize` - PR branch updated with new commits
- `reopened` - Previously closed PR reopened

### Process Flow

```
PR Created/Updated
    ↓
GitHub Actions triggered
    ↓
Checkout code and fetch Development branch
    ↓
Run auto_update_docs.py
    ↓
    ├─ Get git diff
    ├─ Filter source code changes
    ├─ Call Zhipu GLM-4.5-X API
    ├─ Parse AI response (JSON)
    ├─ Update README.md (English)
    ├─ Update README_ZH.md (Chinese)
    ├─ Update docs/*.md (English)
    └─ Update Architecture/*.md (English)
    ↓
Commit documentation updates
    ↓
Push changes to PR branch
    ↓
Create English PR comment
```

## Updated Documents

The system can update the following documentation files:

| File | Language | Updated When |
|------|----------|--------------|
| `README.md` | English | New features, configuration changes |
| `README_ZH.md` | Chinese | New features, configuration changes |
| `docs/packaging-guide.md` | English | Dependency changes |
| `docs/manual_testing_guide.md` | English | New tests |
| `Architecture/gns3_copilot_architecture.md` | English | Architecture changes |

## AI Output Format

The Zhipu GLM-4.5-X API returns a JSON response:

```json
{
  "english_summary": "Added new tool for GNS3 node management",
  "chinese_summary": "新增 GNS3 节点管理工具",
  "doc_updates": {
    "README.md": {
      "section": "Features",
      "content": "- Added new GNS3 node management tool\n  - Supports node creation and deletion"
    },
    "README_ZH.md": {
      "section": "功能列表",
      "content": "- 新增 GNS3 节点管理工具\n  - 支持节点创建和删除"
    }
  }
}
```

## PR Comment Format

The system automatically adds an English comment to your PR:

```markdown
## 📝 Documentation Update Summary

Added new tool for GNS3 node management. The tool supports creating and deleting nodes in GNS3 topologies.

---
*This comment was automatically generated by Zhipu GLM-4.5-X API*
```

## Usage Example

### Creating a PR

1. Make changes to source code
2. Commit your changes
3. Push to a new branch
4. Create a PR to `Development` branch
5. The workflow will automatically:
   - Run in the background
   - Update documentation
   - Add a PR comment

### Viewing Results

Check the **Actions** tab in your PR to see:
- Workflow execution status
- Detailed logs
- Updated documentation files

### Manual Verification

To verify the changes locally:

```bash
# Fetch the updated branch
git fetch origin

# Check the documentation updates
git diff origin/Development...HEAD -- README.md
git diff origin/Development...HEAD -- README_ZH.md
```

## Testing Locally

### Prerequisites

```bash
# Install Python dependencies
pip install requests
```

### Set Environment Variables

```bash
export ZHIPU_API_KEY="your-api-key"
export ZHIPU_MODEL="glm-4-flash"
export PR_NUMBER="test"
export GITHUB_TOKEN="test"
export REPO_OWNER="test"
export REPO_NAME="test"
```

### Run the Script

```bash
python scripts/auto_update_docs.py
```

## Troubleshooting

### Workflow Not Triggering

**Problem**: The workflow doesn't run when creating a PR.

**Solution**:
- Ensure the PR target is the `Development` branch
- Check the workflow file path: `.github/workflows/auto-doc-update.yaml`
- Verify GitHub Actions is enabled in repository settings

### API Key Errors

**Problem**: `ERROR: ZHIPU_API_KEY not found`

**Solution**:
- Check that `ZHIPU_API_KEY` is added to repository Secrets
- Verify the secret name is exactly `ZHIPU_API_KEY`
- Ensure the secret value is correct

### API Call Failures

**Problem**: `API Error 401: Unauthorized`

**Solution**:
- Verify your Zhipu API key is valid
- Check API key has sufficient permissions
- Ensure you have enough API quota

### Permission Denied

**Problem**: `fatal: could not read Username for 'https://github.com'`

**Solution**:
- Enable write permissions for GitHub Actions
- Check workflow permissions: **Settings** → **Actions** → **General**
- Ensure token has `contents: write` permission

### No Documentation Updates

**Problem**: Documentation files not updated

**Solution**:
- Check workflow logs for AI response
- Verify JSON response format is correct
- Ensure documentation files exist
- Check if sections are properly formatted

### Git Push Fails

**Problem**: Changes not pushed to PR branch

**Solution**:
- Verify `GITHUB_TOKEN` has write permissions
- Check if branch is protected
- Ensure PR is not from a fork

## Costs

Using `glm-4-flash` model:

| Metric | Estimate |
|--------|----------|
| Tokens per PR | ~1,500 tokens |
| Cost per PR | ~¥0.00075 |
| Cost for 50 PRs/month | ~¥0.0375 |

The costs are minimal for typical usage.

## Advanced Configuration

### Using a Different Model

To use a different Zhipu model:

1. Add `ZHIPU_MODEL` secret with your preferred model
2. Available models:
   - `glm-4-flash` - Fast, low cost (recommended)
   - `glm-4` - Standard performance
   - `glm-4-plus` - High performance

### Customizing Document Sections

Modify the script to target different sections:

```python
# In scripts/auto_update_docs.py
doc_updates = {
    "README.md": {
        "section": "Custom Section",
        "content": "Your custom content"
    }
}
```

### Skipping Workflow

To skip the automatic documentation update, add `[skip doc]` to your commit message:

```bash
git commit -m "Add new feature [skip doc]"
```

## Contributing

When contributing to the auto-documentation system:

1. Test changes locally before pushing
2. Ensure API key is properly configured
3. Verify workflow execution in Actions tab
4. Check PR comments are generated correctly

## Support

For issues or questions:

1. Check this guide first
2. Review workflow logs in the Actions tab
3. Open an issue in the repository
4. Contact maintainers for assistance

## References

- [Zhipu AI Documentation](https://open.bigmodel.cn/dev/api)
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [PyProject.toml](../pyproject.toml) - Project configuration
- [Packaging Guide](packaging-guide.md) - Packaging documentation
