How to generate reST/sphinx source from python?

Question

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?

Can you explain what format you'd like to generate the reST format from? — Mark Hildreth
– Mark Hildreth, Commented Mar 13, 2011 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
– dantje, Commented Mar 15, 2011 at 5:40

Community · Accepted Answer · 2017-05-23 12:15:21Z

6

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?

edited May 23, 2017 at 12:15

CommunityBot

11 silver badge

answered Mar 13, 2011 at 12:17

mzjn

51.5k16 gold badges139 silver badges265 bronze badges

Sign up to request clarification or add additional context in comments.

5 Comments

dantje Over a year ago

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.

mzjn Over a year ago

@dantje: where does the "knowledge" come from?

dantje Over a year ago

The application reads other files, parses them and should then produce a documentation.

Mark Hildreth Over a year ago

I'm not entirely familiar with the inner workings of Sphinx, but it looks like it uses another library, "docutils" (docutils.sourceforge.net), to help with parsing from the reST. You can take a look at that library and see what it's doing.

dantje Over a year ago

I'll try to implement a restProducer myself and make use of a templating engine like jinja2.

ncoghlan · Accepted Answer · 2011-03-13 11:55:16Z

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.

answered Mar 13, 2011 at 11:55

ncoghlan

41.8k11 gold badges77 silver badges83 bronze badges

Comments

Hieu · Accepted Answer · 2014-11-19 09:31:28Z

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.

Collectives™ on Stack Overflow

How to generate reST/sphinx source from python?

3 Answers 3

5 Comments

Comments

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

5 Comments

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related