Skip to content

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
  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:
  3. ✅ Read and write permissions
  4. 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:

{
  "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:

## 📝 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:
  6. Run in the background
  7. Update documentation
  8. 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:

# 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

# Install Python dependencies
pip install requests

Set Environment Variables

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

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:
  3. glm-4-flash - Fast, low cost (recommended)
  4. glm-4 - Standard performance
  5. glm-4-plus - High performance

Customizing Document Sections

Modify the script to target different sections:

# 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:

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