How to set up automatic documentation generation?

Question

Python

Actually, the question is:
I am currently writing a small project (in Python), I try to document all functions and methods in a similar way:

"""
Generates random secret. Inputs and return are similar to share()'s, except "secret", which is not
in use here.

@param passphrase:  password, if you wish to keep your secret totally confidential
@param recipient:   recipient's e-mail, if you wish to send him an invitation to see your secret
@param ttl:         TTL of your secret, in seconds. Set to one day by default

@type passphrase:   string
@type recipient:    string
@type ttl:          int

@return res:        dict
"""

What is the best way to use to create at least a framework of documentation?

Answer 1

For Python, the de facto standard is: Sphinx (http://sphinx.pocoo.org/contents.html)

Answer 2

Before Sphinx, until the release of Python 2.5 , developers used the epydoc generator and, to be honest, some of its features are severely lacking in Sphinx. For example, automatic (i.e. completely, i.e. without additional markup) library API documentation , as well as building dependency graphs between objects . Well, purely subjective, the design and navigation in the old documentation seemed cleaner and easier to me.
Try it, you might like it.