Skip to content

Commit e15fa3d

Browse files
riverforriverfor
authored
Merge pull request #226 from qpython-android/dev_river
Dev river
2 parents 6ab83f5 + e96cd6b commit e15fa3d

File tree

650 files changed

+9218
-25084
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

650 files changed

+9218
-25084
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,3 +40,5 @@ nosetests.xml
4040
qpython-docs/venv/*
4141
qpython-docs/build/*
4242
qpython-docs/static/*
43+
venv
44+
site

‎CLAUDE.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
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.
8+
9+
## Build Commands
10+
11+
All build commands should be run from the `qpython-docs/` directory:
12+
13+
```bash
14+
cd qpython-docs
15+
```
16+
17+
### Development Build (Local Testing)
18+
19+
Build HTML documentation for local testing:
20+
21+
```bash
22+
make html
23+
```
24+
25+
Output will be in `qpython-docs/build/html/`. Open `build/html/index.html` in a browser to preview.
26+
27+
### Production Build (Deployment)
28+
29+
Build the full site including analytics, static file processing, and copy to the deployment directory:
30+
31+
```bash
32+
./build.sh
33+
```
34+
35+
This script:
36+
1. Removes the existing `docs/` folder at the repository root
37+
2. Runs `make html` to build the documentation
38+
3. Adds Google Analytics and Facebook comments via `add-analytics.py`
39+
4. Renames `_static/` to `static/` and `_images/` to `images/`
40+
5. Copies additional static files (CNAME, favicon.ico, index.html, privacy pages, etc.)
41+
6. Outputs final site to `/docs/` (which is deployed via GitHub Pages)
42+
43+
### Other Useful Commands
44+
45+
```bash
46+
make clean # Remove build artifacts
47+
make linkcheck # Check for broken external links
48+
make doctest # Run doctests in documentation
49+
```
50+
51+
## Project Architecture
52+
53+
### Directory Structure
54+
55+
```
56+
qpython-docs/
57+
├── source/ # Documentation source files (.rst)
58+
│ ├── document.rst # Main toctree (entry point)
59+
│ ├── conf.py # Sphinx configuration
60+
│ ├── _static/ # Static assets (CSS, images)
61+
│ ├── en/ # English documentation
62+
│ │ ├── guide.rst
63+
│ │ ├── faq.rst
64+
│ │ └── ...
65+
│ ├── zh/ # Chinese documentation
66+
│ └── qpython_theme/ # Custom Sphinx theme
67+
│ └── __init__.py
68+
├── build.sh # Production build script
69+
├── add-analytics.py # Post-processor for analytics injection
70+
├── extra.txt # Analytics code template
71+
├── requirements.txt # Python dependencies
72+
└── Makefile # Sphinx build commands
73+
74+
docs/ # Built site (deployment target)
75+
├── index.html # Site homepage
76+
├── document.html # Documentation homepage
77+
├── en/ # Built English docs
78+
├── _sources/ # Source archives (for Sphinx)
79+
└── ...
80+
```
81+
82+
### Key Files
83+
84+
- **`qpython-docs/source/conf.py`**: Sphinx configuration including theme (`qpython_theme`), version, and extensions
85+
- **`qpython-docs/source/document.rst`**: Main documentation entry point with toctree
86+
- **`qpython-docs/build.sh`**: Production build script that processes the Sphinx output and prepares it for deployment
87+
- **`qpython-docs/extra.txt`**: Template for injecting Google Analytics and Facebook comments into HTML
88+
- **`docs/CNAME`**: Configures custom domain (www.qpython.org) for GitHub Pages
89+
90+
### Custom Theme
91+
92+
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.
93+
94+
### Documentation Languages
95+
96+
- English: `qpython-docs/source/en/`
97+
- Chinese: `qpython-docs/source/zh/`
98+
99+
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`.
100+
101+
### Deployment
102+
103+
The `docs/` folder at the repository root is the deployment target. It is served via GitHub Pages. After making changes:
104+
105+
1. Run `./build.sh` to rebuild the site
106+
2. Commit the changes in both `qpython-docs/source/` (source) and `docs/` (built output)
107+
3. Push to deploy

‎build.sh‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
#!/bin/bash
2+
3+
# Build script for QPython documentation
4+
# Supports both English and Chinese
5+
6+
set -e
7+
8+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
9+
cd "$SCRIPT_DIR"
10+
11+
PYTHON="python3.12"
12+
13+
echo "Building QPython documentation..."
14+
echo ""
15+
16+
# Clean previous build
17+
echo "Cleaning previous build..."
18+
rm -rf site
19+
20+
# Build English site
21+
echo "Building English site..."
22+
$PYTHON -m mkdocs build
23+
24+
# Build Chinese site
25+
echo "Building Chinese site..."
26+
$PYTHON -m mkdocs build -f mkdocs-zh.yml
27+
28+
# Create root index.html
29+
echo "Creating root index.html..."
30+
cat > site/index.html << 'EOF'
31+
<!DOCTYPE html>
32+
<html>
33+
<head>
34+
<meta charset="utf-8">
35+
<title>QPython Documentation</title>
36+
<meta http-equiv="refresh" content="0; url=en/">
37+
<style>
38+
body {
39+
font-family: Roboto, Arial, sans-serif;
40+
display: flex;
41+
justify-content: center;
42+
align-items: center;
43+
height: 100vh;
44+
margin: 0;
45+
background: #000;
46+
color: #fff;
47+
}
48+
.container {
49+
text-align: center;
50+
}
51+
.logo {
52+
margin-bottom: 30px;
53+
}
54+
.logo img {
55+
height: 80px;
56+
}
57+
h1 {
58+
font-weight: 300;
59+
margin-bottom: 40px;
60+
}
61+
.languages {
62+
display: flex;
63+
gap: 20px;
64+
justify-content: center;
65+
}
66+
.lang-btn {
67+
padding: 15px 40px;
68+
border: 2px solid #49B300;
69+
color: #49B300;
70+
text-decoration: none;
71+
border-radius: 5px;
72+
transition: all 0.3s;
73+
font-size: 18px;
74+
}
75+
.lang-btn:hover {
76+
background: #49B300;
77+
color: #000;
78+
}
79+
</style>
80+
</head>
81+
<body>
82+
<div class="container">
83+
<div class="logo">
84+
<img src="en/_static/img_logo.png" alt="QPython">
85+
</div>
86+
<h1>Choose your language / 选择语言</h1>
87+
<div class="languages">
88+
<a href="en/" class="lang-btn">English</a>
89+
<a href="zh/" class="lang-btn">中文</a>
90+
</div>
91+
</div>
92+
</body>
93+
</html>
94+
EOF
95+
96+
# Copy additional HTML files from source to site
97+
if ls source/*.html 1> /dev/null 2>&1; then
98+
echo "Copying additional HTML files..."
99+
cp source/*.html site/
100+
fi
101+
102+
# Copy CNAME file if exists
103+
if [ -f source/CNAME ]; then
104+
echo "Copying CNAME file..."
105+
cp source/CNAME site/
106+
fi
107+
108+
echo ""
109+
echo "Build complete!"
110+
echo ""
111+
echo "Output directories:"
112+
echo " - English: site/en/"
113+
echo " - Chinese: site/zh/"
114+
echo " - Root: site/index.html"
115+
echo ""
116+
echo "To preview locally:"
117+
echo " cd site && python -m http.server 8000"

‎deploy.sh‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
#!/bin/bash
2+
3+
# Deploy script for QPython documentation
4+
# Builds the site and deploys to gh-pages branch
5+
6+
set -e
7+
8+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
9+
cd "$SCRIPT_DIR"
10+
11+
# Run build first
12+
echo "Building site..."
13+
./build.sh
14+
15+
# Check if git repository
16+
if [ ! -d .git ]; then
17+
echo "Error: Not a git repository"
18+
exit 1
19+
fi
20+
21+
# Get current branch
22+
CURRENT_BRANCH=$(git branch --show-current)
23+
echo "Current branch: $CURRENT_BRANCH"
24+
25+
# Check if there are uncommitted changes
26+
if ! git diff-index --quiet HEAD --; then
27+
echo "Warning: You have uncommitted changes. Please commit them first."
28+
echo "Uncommitted files:"
29+
git status --short
30+
read -p "Do you want to continue anyway? (y/N) " -n 1 -r
31+
echo
32+
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
33+
echo "Aborted."
34+
exit 1
35+
fi
36+
fi
37+
38+
# Deploy to gh-pages
39+
echo ""
40+
echo "Deploying to gh-pages branch..."
41+
42+
# Create a temporary directory for the site
43+
TEMP_DIR=$(mktemp -d)
44+
cp -r site/* "$TEMP_DIR/"
45+
46+
# Switch to gh-pages branch (create if doesn't exist)
47+
if git show-ref --verify --quiet refs/heads/gh-pages; then
48+
git checkout gh-pages
49+
else
50+
git checkout --orphan gh-pages
51+
git rm -rf . -- ':!deploy.sh'
52+
fi
53+
54+
# Remove old files (except .git and deploy.sh)
55+
find . -maxdepth 1 ! -name '.git' ! -name 'deploy.sh' ! -name '.' ! -name '..' -exec rm -rf {} \;
56+
57+
# Copy new site content
58+
cp -r "$TEMP_DIR"/* .
59+
60+
# Add all files
61+
git add -A
62+
63+
# Commit
64+
COMMIT_MSG="Deploy site - $(date '+%Y-%m-%d %H:%M:%S')"
65+
if git diff --cached --quiet; then
66+
echo "No changes to commit"
67+
else
68+
git commit -m "$COMMIT_MSG"
69+
echo "Committed: $COMMIT_MSG"
70+
fi
71+
72+
# Push to remote with force (gh-pages is safe to force push)
73+
read -p "Push to origin/gh-pages? (y/N) " -n 1 -r
74+
echo
75+
if [[ $REPLY =~ ^[Yy]$ ]]; then
76+
git push origin gh-pages --force
77+
echo ""
78+
echo "Deployed successfully!"
79+
echo "Site will be available at: https://qpython-android.github.io/qpython.org/"
80+
else
81+
echo "Push aborted. You can push manually with: git push origin gh-pages --force"
82+
fi
83+
84+
# Cleanup
85+
rm -rf "$TEMP_DIR"
86+
87+
# Switch back to original branch
88+
git checkout "$CURRENT_BRANCH"
89+
90+
echo ""
91+
echo "Done!"

‎docs/.buildinfo‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎docs/_sources/contributors.rst.txt‎

Lines changed: 0 additions & 61 deletions
This file was deleted.

0 commit comments

Comments
 (0)