[英]How to generate reST/sphinx source from python?
I'd like to generate documentation via reST, but don't want to write the reST source manually, but let a python script do that and then produce other formats (HTML, PDF) with sphinx. 我想通过reST生成文档,但不想手动编写reST源代码,而是让python脚本执行该操作,然后使用sphinx生成其他格式(HTML,PDF)。
Imagine I have a telephone book in binary format. 想象一下,我有一个二进制格式的电话簿。 Now I use a python script to parse this and generate a document with all the names and numbers:
现在我使用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")
Then I would go on to invoke sphinx for generating pdf and html: 然后我会继续调用sphinx来生成pdf和html:
> sphinx phonebook.rst -o phonebook.pdf
> sphinx phonebook.rst -o phonebook.html
Is there a python module (aka restProducer in the example above) that offers an API for generating reST? 是否有一个python模块(在上面的例子中也称为restProducer)提供了一个用于生成reST的API? Or is the best way to just dump reST markup via a couple of print statements?
或者是通过几个打印语句转储reST标记的最佳方法?
See Automatically Generating Documentation for All Python Package Contents . 请参阅自动生成所有Python包内容的文档 。
The upcoming Sphinx 1.1 release includes a sphinx-apidoc.py script. 即将发布的Sphinx 1.1版本包含一个sphinx-apidoc.py脚本。
EDIT: 编辑:
Now that you have explained the problem a bit more, I'd say: go for the "dump reST markup via a couple of print statements" option. 既然你已经解释了这个问题,我会说:通过几个打印语句选择“dump reST markup”选项。 You seem to be thinking along those lines already.
你似乎已经在思考这些问题了。 Why not try to implement a minimalistic
restProducer
? 为什么不尝试实现简约的
restProducer
?
如果你想要docs-without-writing-docs(最多只能给你一个API参考而不是真正的文档),那么Sphinx的autosummary和autodoc扩展可能就是你所追求的。
If your purpose is to programmatically compose the document once, and be able to output in multiple formats, you could have a look at QTextDocument in PyQt Framework. 如果您的目的是以编程方式组合文档一次,并能够以多种格式输出,那么您可以查看PyQt Framework中的QTextDocument。 It is an overkill, though.
不过,这太过分了。
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 supports plaintext, html and ODF. QTextDocumentWriter支持明文,html和ODF。 QPrinter can be used to print to a physical printer or to a PDF file.
QPrinter可用于打印到物理打印机或PDF文件。
However, templating engines like Jinja2 as you mentioned is a neater way to do it. 但是,正如你所提到的,像Jinja2这样的模板引擎是一种更简洁的方法。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.