使用Jenkins publishHTML时如何移除包装页直接访问文档

我现在用Jenkins的HTML Publisher插件，通过publishHTML步骤预览每次构建生成的Sphinx文档，配置代码如下：

publishHTML([
    reportDir: 'path/to/my/html',
    reportFiles: 'index.html',
    reportName: "Generated Documentation",
    keepAll: true
])

默认情况下，插件会生成一层包装HTML，把文档嵌入iframe里。虽然能通过查看源码找到iframe内的页面地址，但我想让Jenkins侧边栏里的文档链接直接指向原生的非iframe页面，有没有办法实现？

几种可行的解决方法 #

• 直接生成原生文档的访问链接
  不用依赖HTML Publisher的默认侧边栏，在构建脚本里添加自定义操作，给当前构建插入一个直接指向原始文档的链接。比如在Jenkinsfile里加入这段代码：

  currentBuild.description = """
  <a href="${BUILD_URL}artifact/path/to/my/html/index.html" target="_blank">打开原生文档</a>
  """
  

  这样构建完成后，在构建详情页就能看到这个直接链接，点击后会打开没有iframe包装的原生Sphinx文档。

• 修改Sphinx配置让链接跳出iframe
  如果想保留HTML Publisher的侧边栏，但让文档内的侧边栏链接自动跳出iframe，可以修改Sphinx的conf.py配置文件，给所有页面链接添加_blank目标：

  html_theme_options = {
      # 根据你使用的主题调整，这里以Read the Docs主题为例
      'navigation_with_keys': True,
      'target': '_blank'
  }
  

  这样文档内的所有导航链接都会在新窗口打开，自动绕过Jenkins的iframe包装。

• 替换插件，直接用工件访问
  要是彻底不想用iframe包装，可以换掉HTML Publisher插件，改用Artifact Deployer插件把Sphinx生成的HTML上传为构建工件。之后通过Jenkins的"工件"页面直接访问文档，所有链接都是原生的，完全没有iframe的问题。

• 修改HTML Publisher的高级配置
  插件本身没有直接关闭iframe的开关，但可以尝试在publishHTML配置里添加escapeXml: false，不过这个参数主要用来控制XML转义，不一定能解决iframe问题。另一种思路是自定义报告页面，把原生文档的内容直接嵌入，但操作起来比较复杂，不如前面几种方法直接。

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