Dev river

.gitignore

@@ -40,3 +40,5 @@ nosetests.xml
 qpython-docs/venv/*
 qpython-docs/build/*
 qpython-docs/static/*
+venv
+site

CLAUDE.md

@@ -0,0 +1,107 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the QPython website and documentation repository (www.qpython.org). QPython is a Python script engine for Android devices. The site is built with [Sphinx](https://www.sphinx-doc.org/) using reStructuredText (.rst) source files.
+
+## Build Commands
+
+All build commands should be run from the `qpython-docs/` directory:
+
+```bash
+cd qpython-docs
+```
+
+### Development Build (Local Testing)
+
+Build HTML documentation for local testing:
+
+```bash
+make html
+```
+
+Output will be in `qpython-docs/build/html/`. Open `build/html/index.html` in a browser to preview.
+
+### Production Build (Deployment)
+
+Build the full site including analytics, static file processing, and copy to the deployment directory:
+
+```bash
+./build.sh
+```
+
+This script:
+1. Removes the existing `docs/` folder at the repository root
+2. Runs `make html` to build the documentation
+3. Adds Google Analytics and Facebook comments via `add-analytics.py`
+4. Renames `_static/` to `static/` and `_images/` to `images/`
+5. Copies additional static files (CNAME, favicon.ico, index.html, privacy pages, etc.)
+6. Outputs final site to `/docs/` (which is deployed via GitHub Pages)
+
+### Other Useful Commands
+
+```bash
+make clean          # Remove build artifacts
+make linkcheck      # Check for broken external links
+make doctest        # Run doctests in documentation
+```
+
+## Project Architecture
+
+### Directory Structure
+
+```
+qpython-docs/
+├── source/                 # Documentation source files (.rst)
+│   ├── document.rst        # Main toctree (entry point)
+│   ├── conf.py             # Sphinx configuration
+│   ├── _static/            # Static assets (CSS, images)
+│   ├── en/                 # English documentation
+│   │   ├── guide.rst
+│   │   ├── faq.rst
+│   │   └── ...
+│   ├── zh/                 # Chinese documentation
+│   └── qpython_theme/      # Custom Sphinx theme
+│       └── __init__.py
+├── build.sh                # Production build script
+├── add-analytics.py        # Post-processor for analytics injection
+├── extra.txt               # Analytics code template
+├── requirements.txt        # Python dependencies
+└── Makefile                # Sphinx build commands
+
+docs/                       # Built site (deployment target)
+├── index.html              # Site homepage
+├── document.html           # Documentation homepage
+├── en/                     # Built English docs
+├── _sources/               # Source archives (for Sphinx)
+└── ...
+```
+
+### Key Files
+
+- **`qpython-docs/source/conf.py`**: Sphinx configuration including theme (`qpython_theme`), version, and extensions
+- **`qpython-docs/source/document.rst`**: Main documentation entry point with toctree
+- **`qpython-docs/build.sh`**: Production build script that processes the Sphinx output and prepares it for deployment
+- **`qpython-docs/extra.txt`**: Template for injecting Google Analytics and Facebook comments into HTML
+- **`docs/CNAME`**: Configures custom domain (www.qpython.org) for GitHub Pages
+
+### Custom Theme
+
+The documentation uses a custom Sphinx theme located at `qpython-docs/source/qpython_theme/`. The theme path is registered in `conf.py` via the `qpython_theme` package.
+
+### Documentation Languages
+
+- English: `qpython-docs/source/en/`
+- Chinese: `qpython-docs/source/zh/`
+
+Each language has its own toctree structure. The master document (`document.rst`) includes the English guide by default and links to Chinese content via `zhindex.rst`.
+
+### Deployment
+
+The `docs/` folder at the repository root is the deployment target. It is served via GitHub Pages. After making changes:
+
+1. Run `./build.sh` to rebuild the site
+2. Commit the changes in both `qpython-docs/source/` (source) and `docs/` (built output)
+3. Push to deploy

build.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+
+# Build script for QPython documentation
+# Supports both English and Chinese
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+PYTHON="python3.12"
+
+echo "Building QPython documentation..."
+echo ""
+
+# Clean previous build
+echo "Cleaning previous build..."
+rm -rf site
+
+# Build English site
+echo "Building English site..."
+$PYTHON -m mkdocs build
+
+# Build Chinese site
+echo "Building Chinese site..."
+$PYTHON -m mkdocs build -f mkdocs-zh.yml
+
+# Create root index.html
+echo "Creating root index.html..."
+cat > site/index.html << 'EOF'
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>QPython Documentation</title>
+    <meta http-equiv="refresh" content="0; url=en/">
+    <style>
+        body {
+            font-family: Roboto, Arial, sans-serif;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            height: 100vh;
+            margin: 0;
+            background: #000;
+            color: #fff;
+        }
+        .container {
+            text-align: center;
+        }
+        .logo {
+            margin-bottom: 30px;
+        }
+        .logo img {
+            height: 80px;
+        }
+        h1 {
+            font-weight: 300;
+            margin-bottom: 40px;
+        }
+        .languages {
+            display: flex;
+            gap: 20px;
+            justify-content: center;
+        }
+        .lang-btn {
+            padding: 15px 40px;
+            border: 2px solid #49B300;
+            color: #49B300;
+            text-decoration: none;
+            border-radius: 5px;
+            transition: all 0.3s;
+            font-size: 18px;
+        }
+        .lang-btn:hover {
+            background: #49B300;
+            color: #000;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="logo">
+            <img src="en/_static/img_logo.png" alt="QPython">
+        </div>
+        <h1>Choose your language / 选择语言</h1>
+        <div class="languages">
+            <a href="en/" class="lang-btn">English</a>
+            <a href="zh/" class="lang-btn">中文</a>
+        </div>
+    </div>
+</body>
+</html>
+EOF
+
+# Copy additional HTML files from source to site
+if ls source/*.html 1> /dev/null 2>&1; then
+    echo "Copying additional HTML files..."
+    cp source/*.html site/
+fi
+
+# Copy CNAME file if exists
+if [ -f source/CNAME ]; then
+    echo "Copying CNAME file..."
+    cp source/CNAME site/
+fi
+
+echo ""
+echo "Build complete!"
+echo ""
+echo "Output directories:"
+echo "  - English: site/en/"
+echo "  - Chinese: site/zh/"
+echo "  - Root: site/index.html"
+echo ""
+echo "To preview locally:"
+echo "  cd site && python -m http.server 8000"

deploy.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+
+# Deploy script for QPython documentation
+# Builds the site and deploys to gh-pages branch
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# Run build first
+echo "Building site..."
+./build.sh
+
+# Check if git repository
+if [ ! -d .git ]; then
+    echo "Error: Not a git repository"
+    exit 1
+fi
+
+# Get current branch
+CURRENT_BRANCH=$(git branch --show-current)
+echo "Current branch: $CURRENT_BRANCH"
+
+# Check if there are uncommitted changes
+if ! git diff-index --quiet HEAD --; then
+    echo "Warning: You have uncommitted changes. Please commit them first."
+    echo "Uncommitted files:"
+    git status --short
+    read -p "Do you want to continue anyway? (y/N) " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        echo "Aborted."
+        exit 1
+    fi
+fi
+
+# Deploy to gh-pages
+echo ""
+echo "Deploying to gh-pages branch..."
+
+# Create a temporary directory for the site
+TEMP_DIR=$(mktemp -d)
+cp -r site/* "$TEMP_DIR/"
+
+# Switch to gh-pages branch (create if doesn't exist)
+if git show-ref --verify --quiet refs/heads/gh-pages; then
+    git checkout gh-pages
+else
+    git checkout --orphan gh-pages
+    git rm -rf . -- ':!deploy.sh'
+fi
+
+# Remove old files (except .git and deploy.sh)
+find . -maxdepth 1 ! -name '.git' ! -name 'deploy.sh' ! -name '.' ! -name '..' -exec rm -rf {} \;
+
+# Copy new site content
+cp -r "$TEMP_DIR"/* .
+
+# Add all files
+git add -A
+
+# Commit
+COMMIT_MSG="Deploy site - $(date '+%Y-%m-%d %H:%M:%S')"
+if git diff --cached --quiet; then
+    echo "No changes to commit"
+else
+    git commit -m "$COMMIT_MSG"
+    echo "Committed: $COMMIT_MSG"
+fi
+
+# Push to remote with force (gh-pages is safe to force push)
+read -p "Push to origin/gh-pages? (y/N) " -n 1 -r
+echo
+if [[ $REPLY =~ ^[Yy]$ ]]; then
+    git push origin gh-pages --force
+    echo ""
+    echo "Deployed successfully!"
+    echo "Site will be available at: https://qpython-android.github.io/qpython.org/"
+else
+    echo "Push aborted. You can push manually with: git push origin gh-pages --force"
+fi
+
+# Cleanup
+rm -rf "$TEMP_DIR"
+
+# Switch back to original branch
+git checkout "$CURRENT_BRANCH"
+
+echo ""
+echo "Done!"