On Wed, 08 Apr 2009, Benoit Thiell wrote: > * 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.
Yes, a change for sub-modules is a bit different topic and probably not of immediate importance. While such a change may be nice, it would not bring us that much profit anyway when compared to the current structure, and when compared to the immediate benefit we get by improving the current documentation. > So in order to have a nice-looking documentation, all docstrings > should follow the guidelines of epydoc. Sure, and the deal is to improve the docs while switching, which is the primary motivation behind docstring standardization. Speaking of nice-looking epydoc documentation, see for example: <http://epydoc.sourceforge.net/api/epydoc.apidoc.VariableDoc-class.html> and friends. We don't have to go that far, of course, but for all inter-module API-like functions, we should have extensive and standardized documentation. I have just committed a new feature for the shellutils library and used this opportunity to convert its docstrings to epytext, so that we may use this file as an example: <http://cdsware.cern.ch/invenio/code-browser/invenio.shellutils-module.html> So, everyone, please don't hesitate to start progressive docstring conversion -- little by little, while *improving* the documentation at the same time. Best regards -- Tibor Simko ** CERN Document Server ** <http://cds.cern.ch/>
