使用ReadTheDocs托管Python API文档的权限与同步问题咨询

我之前也碰到过类似的权限顾虑问题，给你几个实用的方案，完美适配你的场景：

方案一：用细粒度访问令牌限制权限（最省事） #

默认情况下ReadTheDocs请求的是仓库的完全访问权限，但其实我们可以用**细粒度的个人访问令牌（PAT）**来替代，只授予必要的读取权限：

• 在你的代码托管平台（比如GitHub）创建一个Fine-grained PAT，仅给目标主仓库开启读取权限（不要给写入、删除等敏感权限）
• 进入ReadTheDocs的项目设置，找到仓库连接配置，替换默认的OAuth授权为这个PAT
• 在ReadTheDocs的「Advanced Settings」里，设置「Repository directory」为docs/，这样构建过程只会聚焦在文档子目录上

这个方案不用拆分仓库，同时把权限降到了最低，完全满足你的安全需求。

方案二：CI/CD自动同步文档到独立仓库（权限隔离最彻底） #

既然文档是自动生成的，我们可以借助CI/CD工具，每次主仓库更新时自动生成并同步文档到独立的文档仓库，让ReadTheDocs只访问这个隔离的仓库：
比如用GitHub Actions，写一个简单的工作流（存放在主仓库的.github/workflows/sync-docs.yml）：

name: Sync Generated Docs to Docs Repo
on:
  push:
    branches: [ main ]

jobs:
  sync-docs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Main Repo
        uses: actions/checkout@v4

      - name: Set Up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install Docs Dependencies
        run: |
          python -m pip install --upgrade pip
          pip install sphinx sphinx-rtd-theme  # 替换成你的文档生成依赖

      - name: Generate Docs
        run: sphinx-build -b html docs/source docs/build/html  # 替换成你的文档生成命令

      - name: Checkout Docs Repo
        uses: actions/checkout@v4
        with:
          repository: your-username/your-docs-repo  # 替换成你的独立文档仓库
          path: docs-repo
          token: ${{ secrets.DOCS_REPO_PAT }}  # 提前在主仓库设置好文档仓库的写入PAT

      - name: Sync Docs
        run: |
          rm -rf docs-repo/*
          cp -r docs/build/html/* docs-repo/
          cd docs-repo
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git add .
          git commit -m "Sync docs from main repo: ${{ github.sha }}"
          git push

• 提前在主仓库的Secrets里配置好文档仓库的写入PAT
• 配置完成后，每次主仓库推送代码，都会自动生成最新文档并同步到独立仓库，ReadTheDocs只需要连接这个文档仓库即可，完全不碰主仓库，权限问题彻底解决。

方案三：直接在ReadTheDocs上构建子目录（配合受限权限） #

如果你的文档生成工具支持直接从子目录构建，也可以直接在ReadTheDocs的构建设置里指定构建命令，只处理docs/目录，同时配合方案一的细粒度PAT，既保证权限安全，又不用额外的同步步骤。

内容的提问来源于stack exchange，提问作者Robert_LY