On Wed, May 6, 2009 at 9:04 AM, Timmie <timmichel...@gmx-topmail.de> wrote:
> > Hello, > I think we are talking of the same ideas: I think so... great! > > I don't know who you have with push permissions, but I think we should > work > > out the docstring format we want to have, get agreement > There is a clear standard: python docstring standard as in PEP257. The > numpy standard extends this. See an example here: > http://docs.scipy.org/doc/numpy/reference/generated/numpy.arctan.html I had seen (but haven't really studied) PEP257; WOW - did I have to dig to find the docstring source for that arctan module; it looks like it's just docsting - the extensions (I suspect) have to do with this being in a file of just docstrings for generated functions. Anyway, it is a good example - so I'll post the source here (from numpy: core/code_generators/ufunc_docstrings.py). I think this is a good starting template for function definitions, that is these headings (I've reordered them): - Parameters - Returns - Notes - Examples - See Also - References WIll tests in docstrings work ok? Should we have a subheading: "Tests"? --------[ begin example docstring for arctan function - this would appear after the def arctan: ]--------------- """ Trigonometric inverse tangent, element-wise. The inverse of tan, so that if ``y = tan(x)`` then ``x = arctan(y)``. Parameters ---------- x : array_like Input values. `arctan` is applied to each element of `x`. Returns ------- out : ndarray Out has the same shape as `x`. Its real part is in ``[-pi/2, pi/2]``. It is a scalar if `x` is a scalar. See Also -------- arctan2 : Calculate the arctan of y/x. Notes ----- `arctan` is a multivalued function: for each `x` there are infinitely many numbers `z` such that `tan(z) = x`. The convention is to return the angle `z` whose real part lies in `[-pi/2, pi/2]`. For real-valued input data types, `arctan` always returns real output. For each value that cannot be expressed as a real number or infinity, it yields ``nan`` and sets the `invalid` floating point error flag. For complex-valued input, `arctan` is a complex analytical function that has branch cuts `[1j, infj]` and `[-1j, -infj]` and is continuous from the left on the former and from the right on the latter. The inverse tangent is also known as `atan` or ``tan^-1``. References ---------- .. [1] M. Abramowitz and I.A. Stegun, "Handbook of Mathematical Functions", 10th printing, 1964, pp. 79. http://www.math.sfu.ca/~cbm/aands/ .. [2] Wikipedia, "Inverse trigonometric function", http://en.wikipedia.org/wiki/Arctan Examples -------- We expect the arctan of 0 to be 0, and of 1 to be :math:`\\pi/4`: >>> np.arctan([0, 1]) array([ 0. , 0.78539816]) >>> np.pi/4 0.78539816339744828 Plot arctan: >>> import matplotlib.pyplot as plt >>> x = np.linspace(-10, 10) >>> plt.plot(x, np.arctan(x)) >>> plt.axis('tight') >>> plt.show() """ ---------[ end exaxmple ] -------------------- --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "web2py Web Framework" group. To post to this group, send email to web2py@googlegroups.com To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/web2py?hl=en -~----------~----~----~----~------~----~------~--~---
