如何从Python生成reST/sphinx源？
我想通过 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？或者是通过几个打印语句转储剩余标记的最佳方法？
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.
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:
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 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? Or is the best way to just dump reST markup via a couple of print statements?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（3）
请参阅自动生成所有 Python 包内容的文档。
即将推出的 Sphinx 1.1 版本包含 sphinx-apidoc.py 脚本。
编辑：
现在您已经对问题做了更多解释，我想说：选择“通过几个打印语句转储 reST 标记”选项。你似乎已经在沿着这些思路思考了。为什么不尝试实现一个简约的
restProducer？See Automatically Generating Documentation for All Python Package Contents.
The upcoming Sphinx 1.1 release includes a sphinx-apidoc.py script.
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. You seem to be thinking along those lines already. Why not try to implement a minimalistic
restProducer?如果您想要 docs-without-writing-docs （最多只能为您提供 API 参考而不是真正的文档），那么 autosummary 和 autodoc 扩展可能就是您想要的正在追赶。
If you want docs-without-writing-docs (which will at best give you an API reference rather than real docs), then the autosummary and autodoc extensions for Sphinx may be what you're after.
如果您的目的是以编程方式编写一次文档，并能够以多种格式输出，您可以看看 PyQt Framework 中的 QTextDocument。不过，这有点矫枉过正了。
QTextDocumentWriter 支持纯文本、html 和 ODF。 QPrinter 可用于打印到物理打印机或到 PDF 文件。
然而，像您提到的 Jinja2 这样的模板引擎是一种更简洁的方法。
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. It is an overkill, though.
QTextDocumentWriter supports plaintext, html and ODF. QPrinter can be used to print to a physical printer or to a PDF file.
However, templating engines like Jinja2 as you mentioned is a neater way to do it.