10

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?

dantje
  • 1,739
  • 1
  • 13
  • 25
  • Can you explain what format you'd like to generate the reST format from? – Mark Hildreth Mar 13 '11 at 22:02
  • Basically from internal state of the program. I have got some hashes and lists and now it would like to iterate thru these and maybe generate a section in a document for each entry in these data structures. – dantje Mar 15 '11 at 05:40

3 Answers3

6

  1. See Automatically Generating Documentation for All Python Package Contents.

  2. 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?

Community
  • 1
  • 1
mzjn
  • 48,958
  • 13
  • 128
  • 248
  • It is not a python module or package I'd like to document. The python script just has some knowledge it should format into a reST source. – dantje Mar 13 '11 at 21:46
  • @dantje: where does the "knowledge" come from? – mzjn Mar 14 '11 at 15:57
  • The application reads other files, parses them and should then produce a documentation. – dantje Mar 15 '11 at 05:38
  • I'm not entirely familiar with the inner workings of Sphinx, but it looks like it uses another library, "docutils" (http://docutils.sourceforge.net/), to help with parsing from the reST. You can take a look at that library and see what it's doing. – Mark Hildreth Mar 15 '11 at 18:58
  • I'll try to implement a restProducer myself and make use of a templating engine like jinja2. – dantje Mar 17 '11 at 21:22
4

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.

ncoghlan
  • 40,168
  • 10
  • 71
  • 80
0

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.

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. 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.

Hieu
  • 7,138
  • 2
  • 42
  • 34