如何从Python生成reST/sphinx源代码？

Question

我想通过reST生成文档，但不想手动写reST的源文件，而是希望用一个Python脚本来完成这个工作，然后用sphinx生成其他格式（比如HTML和PDF）。

想象一下，我有一本二进制格式的电话簿。现在我用一个Python脚本来解析这个电话簿，并生成一个包含所有名字和电话号码的文档：

  phone_book = PhonebookParser("somefile.bin")

  restdoc = restProducer.NewDocument()
  for entry in phone_book:
    restdoc.add_section( title = entry.name, body = entry.number )

  restdoc.write_to_file("phonebook.rst")

接着，我会调用sphinx来生成PDF和HTML格式的文档：

  > sphinx phonebook.rst -o phonebook.pdf
  > sphinx phonebook.rst -o phonebook.html

有没有一个Python模块（比如上面提到的restProducer），可以提供生成reST的接口？还是说最简单的方法就是通过几个打印语句直接输出reST的标记？

Answer 1

如果你的目的是一次性编写文档，然后能够输出成多种格式，你可以看看PyQt框架中的QTextDocument。不过，这个方法可能有点复杂。

from PyQt4.QtGui import *
import sys

doc = QTextDocument()
cur = QTextCursor(doc)

d_font = QFont('Times New Roman')
doc.setDefaultFont(d_font)

table_fmt = QTextTableFormat()
table_fmt.setColumnWidthConstraints([
    QTextLength(QTextLength.PercentageLength, 30),
    QTextLength(QTextLength.PercentageLength, 70)
    ])
table = cur.insertTable(5,2, table_fmt)
cur.insertText('sample text 1')
cur.movePosition(cur.NextCell)
cur.insertText('sample text 2')

# Print to a pdf file
# QPrinter: Must construct a QApplication before a QPaintDevice
app = QApplication(sys.argv)
printer = QPrinter(QPrinter.HighResolution)
printer.setOutputFormat(QPrinter.PdfFormat)
printer.setOutputFileName('sample.pdf')

# Save to file
writer = QTextDocumentWriter()
writer.setFormat(writer.supportedDocumentFormats()[1])
writer.setFileName('sample.odt')
writer.write(doc)

QTextDocumentWriter支持纯文本、HTML和ODF格式。QPrinter可以用来打印到实体打印机或者生成PDF文件。

不过，像你提到的Jinja2这样的模板引擎，使用起来会更简单、更整洁。

Answer 2

如果你想要一种不需要自己写文档的方法（这样得到的最多只是一个API参考，而不是完整的文档），那么Sphinx的autosummary和autodoc扩展可能正是你需要的。

Answer 3

1. 可以查看这个链接：自动生成所有Python包内容的文档。

2. 即将发布的Sphinx 1.1版本中包含一个名为sphinx-apidoc.py的脚本。

编辑：

既然你已经稍微解释了问题，我建议你可以尝试“通过几个打印语句输出reST标记”的方法。你似乎已经在这个方向上思考了。为什么不试着实现一个简单的restProducer呢？