Hi gang: Several weeks ago we have discussed an idea that it would be perhaps interesting to publish an HTML source code documentation browser for the CDS Invenio sources.
Such a code browser usually does not offer much more beyond what a pydoc and a good code editor with symbol lookup capabilities already do - but we may perhaps take this as an opportunity to clean our codebase documentation, which is *always* a good thing to do, so... :) So I have prepared a sample CDS Invenio HTML code documentation browser: <http://cdsware.cern.ch/invenio/code-browser/> I happen to like `epydoc' so I have prepared the demo with it. Epydoc uses by default an `epytext' markup language inside docstrings, that looks like this: | def x_intercept(m, b): | """ | Return the x intercept of the line M{y=m*x+b}. The X{x intercept} | of a line is the point at which it crosses the x axis (M{y=0}). | | This function can be used in conjuction with L{z_transform} to | find an arbitrary function's zeros. | | @type m: number | @param m: The slope of the line. | @type b: number | @param b: The y intercept of the line. The X{y intercept} of a | line is the point at which it crosses the y axis (M{x=0}). | @rtype: number | @return: the x intercept of the line M{y=m*x+b}. | """ | return -b/m Please look at <http://epydoc.sourceforge.net/manual-epytext.html> to see what epydoc/epytext can do. N: We currently use several docstring styles in the CDS Invenio sources (none, free style, lisp style, javadoc style). Our code browser demo page for CDS Invenio does not look too good, because we don't use the epytext markup. (Well, epydoc could use the Javadoc markup with some @type extensions too, but we are not complete there either). Once we choose some code documentation browser software and some docstring markup, then we should progressively migrate all our docstrings towards the new style for the whole codebase. Q: Do you like epydoc/epytext combination? Okay to go for it? Q: Do you have any alternative proposals to epydoc/epytext? Best regards -- Tibor Simko ** CERN Document Server ** <http://cds.cern.ch/>
