文档部署

快速入门

本地构建并服务文档：

cd docs/
./build_docs.sh
./validate_docs.sh

验证脚本将提示启动本地服务器，地址为 http://localhost:8080。

GitHub 页面

自动化部署

该仓库包含用于自动部署到 GitHub Pages 的 GitHub Actions 工作流。

设置步骤：

1. 在仓库设置中启用 GitHub Pages：

  • 转到存储库 设置 > 页面

  • 将源设置为 GitHub Actions

  1. 推送到主分支 - 文档将自动生成

  2. 访问文档地址：https://yourusername.github.io/ToolUniverse/

手动部署 GitHub Pages：

# Build documentation
cd docs/
./build_docs.sh

# Copy to gh-pages branch
git checkout --orphan gh-pages
git rm -rf .
cp -r docs/_build/html/* .
git add .
git commit -m "Deploy documentation"
git push -f origin gh-pages

阅读文档

自动化设置

1. 将代码库连接到 ReadTheDocs：

  1. 配置文件 .readthedocs.yaml 已经提供

  2. 文档会在提交时自动生成

.readthedocs.yaml 文件指定：

  • Python 版本：3.8+

  • 要求: docs/requirements.txt

  • Sphinx 配置：docs/conf.py

  • 输出格式：HTML、PDF

本地开发服务器

自动重新加载开发

在开发过程中使用 sphinx-autobuild 实现实时重载：

# Install if not already installed
pip install sphinx-autobuild

# Start development server
cd docs/
sphinx-autobuild . _build/html --port 8080

当文件发生更改时，服务器将自动重建。

生产服务器

对于生产环境托管，请使用合适的 Web 服务器：

Nginx 示例：

server {
    listen 80;
    server_name docs.yourdomain.com;
    root /path/to/ToolUniverse/docs/_build/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Apache 示例：

<VirtualHost *:80>
    ServerName docs.yourdomain.com
    DocumentRoot /path/to/ToolUniverse/docs/_build/html
    DirectoryIndex index.html
</VirtualHost>

Docker 部署

Nginx 的 Dockerfile

在 docs 目录中创建 Dockerfile：

FROM nginx:alpine
COPY _build/html /usr/share/nginx/html
EXPOSE 80

构建并运行：

cd docs/
./build_docs.sh
docker build -t tooluniverse-docs .
docker run -p 8080:80 tooluniverse-docs

多阶段构建

对于包含构建的小型镜像：

# Build stage
FROM python:3.9-slim as builder
WORKDIR /docs
COPY . .
RUN pip install -r requirements.txt && \
    sphinx-build -b html . _build/html

# Serve stage
FROM nginx:alpine
COPY --from=builder /docs/_build/html /usr/share/nginx/html
EXPOSE 80

持续集成

GitHub 操作

.github/workflows/docs.yml 工作流：

  • 触发器：推送到主分支，拉取请求

  • 构建：HTML 和 PDF 文档

  • 部署：部署到 GitHub Pages（主分支）

  • 测试：链接检查，验证

在仓库的 Actions 选项卡中查看工作流状态。

自定义 CI/CD

对于其他持续集成系统，请使用以下命令：

# Install dependencies
pip install -r docs/requirements.txt

# Build documentation
cd docs/
sphinx-build -b html . _build/html

# Validate build
./validate_docs.sh

# Deploy (custom logic)
./deploy.sh

故障排除

常见问题

构建失败，出现模块导入错误：

# Install project in editable mode
pip install -e .
cd docs/
./build_docs.sh

缺少静态文件：

# Clean and rebuild
cd docs/
make clean
./build_docs.sh

断链：

# Check with sphinx-build
sphinx-build -b linkcheck . _build/linkcheck

部署时的权限错误：

# Fix file permissions
chmod +x docs/*.sh

性能优化

对于大型文档站点：

  1. 启用并行构建：

    # In conf.py
numjobs = 4  # Use multiple processes

  2. 优化图像：

    # Compress images in _static/
find _static/ -name "*.png" -exec optipng {} \;

  3. 使用 CDN 加速静态文件：

    # In conf.py
html_baseurl = 'https://cdn.yourdomain.com/'

监控

健康检查

创建一个简单的健康检查端点：

# Check if documentation is accessible
curl -f https://yourdocs.com/ || exit 1

分析功能

将 Google Analytics 添加到 conf.py：

html_theme_options = {
    'analytics_id': 'UA-XXXXXXX-1',
}

或者将自定义跟踪代码添加到 _templates/layout.html。

备份与恢复

备份策略

  1. 版本控制：文档源代码存储于 Git 中

  2. 构建产物：归档已构建的文档

  3. 依赖项：在 requirements.txt 中固定版本号

# Create backup
tar -czf docs-backup-$(date +%Y%m%d).tar.gz _build/

恢复

# Restore from backup
tar -xzf docs-backup-20231201.tar.gz

# Or rebuild from source
./build_docs.sh

部署配置已完成。文档系统现支持多个部署目标，并实现了自动化的CI/CD集成。