Hi Tibor.
On Mon, 6 Apr 2009, Tibor Simko wrote:
Hi gang:
So I have prepared a sample CDS Invenio HTML code documentation browser:
<http://cdsware.cern.ch/invenio/code-browser/>
Q: Do you like epydoc/epytext combination? Okay to go for it?
OK. I really like the process of making Invenio simpler to learn for
newcomers and maybe this browsable documentation can help to achieve this.
I also happen to like the docstring format.
Some remarks concerning the demo you set up:
* The display of the documentation is not so nice due to the fact that we
have only one huge 'Python' module (invenio) (not counting rare other
ones) containing all files of each 'Invenio' module. I know that this is a
major change but it would look really nicer if our module structure would
be something like 'invenio.bibedit.bibrecord'. (My opinion is also that
this structure makes much more sense than the one we are currently using.
But that is another discussion.)
* Whenever epydoc considers that there is a formatting problem in a
docstring, it shows it as a literal block
(http://epydoc.sourceforge.net/epytext.html#literal). Here is an
example:
http://cdsware.cern.ch/invenio/code-browser/invenio.access_control_admin-module.html#acc_add_action
See the difference between acc_add_action and acc_delete_action.
So in order to have a nice-looking documentation, all docstrings should
follow the guidelines of epydoc.
Best regards
--
Benoit Thiell ** CERN Document Server ** <http://cds.cern.ch/>
