从 YAML 文件中引用 sphinx 生成的 Python 文档答案

【问题标题】：referencing sphinx generated Python docs from YAML file从 YAML 文件中引用 sphinx 生成的 Python 文档
【发布时间】：2014-11-24 22:42:30
【问题描述】：

我们有一个使用 Sphinx 记录的内部 python API。系统的一部分将 YAML 用于包含对使用 API 的 py 文件的引用的配置文件。我被要求查看是否有办法使用 sphinx 将 YAML 配置文件链接到适当的 API 文档。我一直在研究 google、here 和 sphinx 网站，看起来我可以使用 intersphinx，但我不清楚如何在两者之间建立联系。

例如：这里是 yaml 配置文件：

HALT_LEVEL: Any
SUITE: "Checkin Tests"
DESCRIPTION: "checkin test suite"

TESTLIST:
    - TESTCASE: install stuff
      DESC: "Installs RPM"
      TESTGROUP: sprint_0
      TESTFILE: install_stuff.py   # I would like to turn this into a link to our sphinx docs
                                   # for this. This file is already part of sphinx docs"

因此，当有人查看上述文件的 html/sphinx 版本时，他们可以点击 install_stuff.py 并将他们带到现有的文档

这可能吗？

提前致谢，格雷格。

【问题讨论】：

标签： python-sphinx

【解决方案1】：

仅适用于可能感兴趣的人。我能够做到这一点，但没有使用 Sphinx。我使用 pyyaml 读取文件并使用 pygments 生成 html，然后破解生成的 html。

由于 pygments 似乎不允许实时 href 链接添加什么我是什么

# create a yaml string using pyyaml and then modify the string.
href = '[ahref="%s"]%s[/a]' % (hrefData, hrefString)
yamldata['KEYWORD'][idx]['HOST'] = href

这会将引用的 yaml 更改为类似于 '[ahref="http://example.com"]Example.com[/a]' 的字符串。括号使生成 html 后更容易更改。在代码的更下方，我使用 pygments 生成 html

htmlpage = highlight(yamldata,lexer, HtmlFormatter(full=True, title=yamldata['TITLE']))

现在我将上面创建的 href 转换为真正的 href：

webpage = htmlpage.replace('&#39;', '').replace('ahref', 'a href').replace('[','<').replace(']','>').replace('&quot;','"')

【讨论】：