如何在DevOps流水线中部署Sphinx构建的Python库静态文档网站？

适配Azure DevOps的部署方案 #

基于你当前的流水线配置，以下几种方案可以直接将静态文档部署为可访问的网站：

1. 部署到Azure Static Web Apps #

这是托管静态站点的轻量化方案，适合公开或内部访问的文档。在现有流水线中添加以下任务：

- task: AzureStaticWebApp@0
  displayName: "部署到Azure静态Web应用"
  inputs:
    app_location: ""  # 无需填写，目标为静态内容
    api_location: ""   # 无后端API，留空
    output_location: "./docs/_build/html"  # 静态文件路径
    azure_static_web_apps_api_token: $(AZURE_STATIC_WEB_APPS_TOKEN)

• 提前在Azure门户创建Static Web Apps实例，获取部署令牌并添加到Azure DevOps的变量组中。

2. 部署到Azure Blob存储（启用静态网站托管） #

适合需要低成本存储+静态访问的场景：

1. 在Azure门户创建Blob存储账户，开启静态网站功能，设置默认文档为index.html，错误文档为404.html。
2. 在流水线中添加文件复制任务：

- task: AzureFileCopy@4
  displayName: "部署到Azure Blob存储"
  inputs:
    SourcePath: "./docs/_build/html/*"
    azureSubscription: "<你的Azure服务连接名称>"
    Destination: "AzureBlob"
    storage: "<你的存储账户名称>"
    ContainerName: "$web"  # 静态网站默认容器名

3. 部署到Azure DevOps Wiki（内部团队访问） #

如果仅需内部团队查看，可将静态文档发布到Wiki：

• 安装PublishWikiDocumentation扩展后添加对应任务，或通过脚本将HTML转换为Markdown上传（注意：Sphinx HTML转Markdown可能丢失部分格式）。

完整流水线配置示例（Azure Static Web Apps版） #

trigger:
  branches:
    include:
      - main

pool:
  vmImage: windows-latest

steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: "3.10"
    displayName: "使用Python 3.10"

  - script: python -m pip install nox
    displayName: "安装依赖"

  - script: nox -s docs
    displayName: "构建静态文档"

  - task: PublishBuildArtifacts@1
    displayName: "发布HTML工件"
    inputs:
      pathToPublish: "./docs/_build/html/"
      artifactName: "documentation"

  # 新增部署步骤
  - task: AzureStaticWebApp@0
    displayName: "部署到Azure静态Web应用"
    inputs:
      app_location: ""
      api_location: ""
      output_location: "./docs/_build/html"
      azure_static_web_apps_api_token: $(AZURE_STATIC_WEB_APPS_TOKEN)

注意事项 #

• 确保Azure服务连接已配置完成，拥有目标资源的部署权限。
• 若使用Blob存储，需设置正确的存储账户公共访问级别，或通过SAS令牌控制访问。
• 部署完成后可配置自定义域名和CDN，提升访问体验。

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