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的API？或者是通过几个打印语句转储reST标记的最佳方法？

Answer 1

请参阅Automatically Generating Documentation for All Python Package Contents。
即将发布的Sphinx 1.1版本包含sphinx-apidoc.py脚本。

编辑：

既然您已经解释了这个问题，我会说：通过几个打印语句选择“dump reST markup”选项。你似乎已经在思考这些问题了。为什么不尝试实现简约restProducer？

Answer 2

如果您需要docs-without-writing-docs（最多只能为您提供API参考而不是真实文档），那么Sphinx的autosummary和autodoc扩展可能就是您的'重新开始。

Answer 3

如果您的目的是以编程方式组合文档一次，并能够以多种格式输出，那么您可以查看PyQt Framework中的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这样的模板引擎是一种更简洁的方法。

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

3 个答案: