当前位置：文江博客话题详情

让 Sphinx 从 pydoc 生成 RST 类文档

发布于 2024-08-29 06:17:01 字数 521 浏览 7 评论 0原文

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

问题是文档使用 Python docstrings （该模块是用 C 编写的，但它可能确实没关系）并且类文档必须转换为可用于 Sphinx 的形式。

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

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

原文

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

長街聽風 2024-09-05 06:17:01

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，您可以简单地将其重定向或复制到其他地方。

The autodoc does generate RST only there is no official way to get it out of it. The easiest hack to get it was by changing sphinx.ext.autodoc.Documenter.add_line method to emit me the line it gets.

As all I want is one time migration, output to stdout is good enough for me:

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)

Now autodoc prints generated RST on stdout while running and you can simply redirect or copy it elsewhere.

回复收藏 0 原文

少女七分熟 2024-09-05 06:17:01

猴子修补自动文档，使其无需编辑任何内容即可工作：

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

monkey patching autodoc so it works without needing to edit anything:

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

回复收藏 0 原文