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?

Answer 1

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?

Answer 2

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.