使Sphinx从PYDOC生成RST类文档

2022-04-21 00:00:00 python python-sphinx pydoc

问题描述

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

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

有sphinx.ext.autodoc,但它会自动将当前文档字符串放到文档中。我希望在(RST)中基于当前文档字符串生成一个源文件,然后我可以手动编辑和改进它。

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


解决方案

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会在运行时在标准输出上打印生成的RST,您只需将其重定向或复制到其他位置即可。

相关文章