在GitLab中构建Sphinx文档前集成外部仓库的方法

以下是几种实用的解决方案，适配不同场景：

方案1：使用Git子模块（Submodule） #

适合需要长期跟踪外部仓库特定版本的场景：

• 本地项目中添加外部仓库作为子模块：

  git submodule add <外部仓库Git地址> docs/external_deps
  git commit -m "Add external repo as submodule"
  git push
  

• 在.gitlab-ci.yml的构建步骤中确保拉取子模块：

  build_docs:
    stage: build
    script:
      - git submodule update --init --recursive
      - pip install sphinx
      - sphinx-build -b html docs/source docs/build/html
  

• 修改conf.py，用相对路径添加外部仓库到Python路径：

  import os
  import sys
  # 子模块位于docs/external_deps，从conf.py所在目录（通常是source）向上一级定位
  sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '../external_deps')))
  

方案2：CI流水线中直接克隆外部仓库 #

适合临时拉取外部仓库最新版本、不想维护子模块的场景：

• 在.gitlab-ci.yml的构建阶段先克隆外部仓库到指定目录：

  build_docs:
    stage: build
    script:
      - apt-get update && apt-get install -y git python3-pip
      - pip install sphinx
      # 克隆外部仓库到docs目录下的external文件夹
      - git clone <外部仓库Git地址> docs/external
      # 执行Sphinx构建
      - sphinx-build -b html docs/source docs/build/html
  

• 如果外部仓库是私有，使用GitLab Deploy Token授权：
  1. 在外部仓库的设置 > 仓库 > Deploy tokens中创建一个有读取权限的token
  2. 在当前项目的CI/CD > 变量中添加DEPLOY_TOKEN_USER和DEPLOY_TOKEN两个变量，值对应创建的token用户名和密码
  3. 修改克隆命令：

     git clone https://$DEPLOY_TOKEN_USER:$DEPLOY_TOKEN@<外部仓库Git地址> docs/external
     

• 同样在conf.py中用相对路径添加外部仓库的Python路径，和方案1的代码一致。

方案3：将外部仓库作为Python依赖安装 #

如果外部仓库是标准Python包结构（有setup.py/pyproject.toml），可以直接通过pip安装：

• 在项目的requirements.txt中添加外部仓库地址：

  git+<外部仓库Git地址>@<指定分支或标签>
  

• 在.gitlab-ci.yml中先安装依赖再构建：

  build_docs:
    stage: build
    script:
      - pip install -r requirements.txt
      - pip install sphinx
      - sphinx-build -b html docs/source docs/build/html
  

• 这种方式下，外部仓库会被安装到Python的site-packages目录，conf.py中无需额外添加路径，直接导入即可。

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