让Sphinx从pydoc生成RST类文档

时间:2010-04-19 14:28:47

标签: python python-sphinx pydoc

我目前正在将所有现有(不完整)文档迁移到Sphinx

问题是文档使用Python docstrings(模块是用C编写的,但它可能无关紧要),类文档必须转换为可用于Sphinx的表单。

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

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

3 个答案:

答案 0 :(得分:13)

autodoc确实生成了RST,但没有正式的方法可以将其从中删除。获得它的最容易的方法是更改​​sphinx.ext.autodoc.Documenter.add_line方法以向我发出它所获得的行。

正如我想要的只是一次性迁移,输出到stdout对我来说已经足够了:

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在运行时打印出stdout上的RST,你可以简单地将其重定向或复制到别处。

答案 1 :(得分:2)

猴子修补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

答案 2 :(得分:0)

据我所知,没有自动化工具可以做到这一点。因此,我的方法是编写一个小脚本来读取相关模块(基于sphinc.ext.autodoc)并将doc字符串抛出到一个文件中(格式化正确)。