让 Sphinx 从 pydoc 生成 RST 类文档答案

【问题标题】：Make Sphinx generate RST class documentation from pydoc让 Sphinx 从 pydoc 生成 RST 类文档
【发布时间】：2010-04-19 14:28:46
【问题描述】：

我目前正在将所有现有（不完整）文档迁移到 Sphinx。

问题是文档使用Python docstrings（模块是用C写的，但可能没关系），类文档必须转换成Sphinx可用的形式。

有sphinx.ext.autodoc，但它会自动将当前文档字符串放入文档中。我想根据当前的文档字符串在 (RST) 中生成一个源文件，然后我可以手动对其进行编辑和改进。

如何将文档字符串转换为 Sphinx 的 RST？

【问题讨论】：

标签： python python-sphinx pydoc

【解决方案1】：

autodoc 确实会生成 RST，只是没有官方方法可以将其取出。获得它的最简单方法是更改 sphinx.ext.autodoc.Documenter.add_line 方法以向我发出它得到的行。

我想要的只是一次迁移，输出到标准输出对我来说已经足够了：

def add_line(self, line, source, *lineno):
    """Append one line of generated reST to the output."""
    print(self.indent + line)
    self.directive.result.append(self.indent + line, source, *lineno)

现在 autodoc 在运行时在标准输出上打印生成的 RST，您可以简单地重定向或复制到其他地方。

【讨论】：

很好，如果您使用 virtualenv，我只想添加该文件的目录~/.virtualenvs/docs/lib/python2.7/site-packages/sphinx/ext/。文件名当然是autodoc.py
像我这样的新手，记得在Python 3.x中使用parens，新行应该是print(self.indent + line)

【解决方案2】：

monkey 修补 autodoc 使其无需编辑任何内容即可工作：

import sphinx.ext.autodoc
rst = []
def add_line(self, line, source, *lineno):
    """Append one line of generated reST to the output."""
    rst.append(line)
    self.directive.result.append(self.indent + line, source, *lineno)
sphinx.ext.autodoc.Documenter.add_line = add_line
try:
    sphinx.main(['sphinx-build', '-b', 'html', '-d', '_build/doctrees', '.', '_build/html'])
except SystemExit:
    with file('doc.rst', 'w') as f:
        for line in rst:
            print >>f, line

【讨论】：

【解决方案3】：

据我所知，没有自动化工具可以做到这一点。因此，我的方法是编写一个小脚本来读取相关模块（基于 sphinc.ext.autodoc）并将文档字符串放入文件中（格式适当）。

【讨论】：