Как сгенерировать исходный код reST / sphinx из python? - PullRequest
Новая
       63

Как сгенерировать исходный код reST / sphinx из python?

6 голосов
/ 13 марта 2011

Я бы хотел сгенерировать документацию через reST, но не хочу писать исходный код reST вручную, но пусть это делает скрипт python, а затем создает другие форматы (HTML, PDF) с помощью sphinx.

Представьте, что у меня есть телефонная книга в двоичном формате. Теперь я использую скрипт 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 в приведенном выше примере), который предлагает API для генерации reST? Или это лучший способ просто сбросить разметку reST через пару операторов print?

Ответы [ 3 ]

5 голосов
/ 13 марта 2011

  1. См. Автоматическое создание документации для всего содержимого пакета Python .

  2. Предстоящий выпуск Sphinx 1.1 включает sphinx-apidoc.py script.

РЕДАКТИРОВАТЬ:

Теперь, когда вы объяснили проблему немного подробнее, я бы сказал: идидля опции «сбросить разметку через пару операторов печати».Кажется, ты уже думаешь в том же духе.Почему бы не попробовать реализовать минималистичный restProducer?

3 голосов
/ 13 марта 2011

Если вам нужны документы-без-записи-документов (которые в лучшем случае дадут вам справочную информацию по API, а не реальные документы), тогда расширения для автоматического ввода и autodoc для Sphinx могутбудь тем, что тебе нужно.

0 голосов
/ 19 ноября 2014

Если ваша цель состоит в том, чтобы программно составить документ один раз и иметь возможность вывода в нескольких форматах, вы можете взглянуть на QTextDocument в PyQt Framework.Однако это излишнее количество. 

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, - более удобный способ сделать это.

...