如何从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的API？还是通过几个打印语句来转储reST标记是最好的方法？

- dantje

---

你能解释一下你想从哪种格式生成reST格式吗？ - Mark Hildreth

基本上从程序的内部状态来看，我已经得到了一些哈希和列表，现在想要遍历它们，并且可能为这些数据结构中的每个条目生成文档中的一个部分。 - dantje

Answer 1

1. 请参考自动生成所有Python包内容文档。

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

编辑：

现在您已经更详细地解释了问题，我建议：采用“通过几个打印语句转储reST标记”选项。您似乎已经在考虑这些方面。为什么不尝试实现一个最小化的restProducer呢？

- mzjn

---

这不是我想要记录文档的Python模块或包。这个Python脚本只是有一些需要格式化成reST源代码的知识。 - dantje

@dantje: “知识”从哪里来？ - mzjn

该应用程序读取其他文件，对其进行解析，然后应生成文档。 - dantje

我并不完全熟悉Sphinx的内部工作原理，但看起来它使用了另一个库“docutils”（http://docutils.sourceforge.net/）来帮助解析reST。你可以查看该库并了解它在做什么。 - Mark Hildreth

我会尝试自己实现一个restProducer，并使用像jinja2这样的模板引擎。 - dantje

Answer 2

如果你想要不需要编写文档的文档（最多只能提供API参考而非真正的文档），那么Sphinx的autosummary和autodoc扩展可能是你需要的。请参考autosummary和autodoc。

- ncoghlan

Answer 3

如果您的目的是通过编程一次性地组成文档，并能够以多种格式输出，您可以查看 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 这样的模板引擎是更加整洁的方式。

- Hieu