[Numpy-discussion] Howto document constants?

Ralf Gommers ralf.gommers@googlemail....
Sat Nov 14 03:37:18 CST 2009

On Sat, Nov 14, 2009 at 4:30 AM, Pierre GM <pgmdevlist@gmail.com> wrote:

> On Nov 13, 2009, at 9:54 PM, Charles R Harris wrote:
> > Hi All,
> >
> > The documentation documentation says to document constants like
> functions. So if a module defines a constant is it documented like so:
> >
> > myconstant = 1
> > """Blah and blah"""
> >
> > That doesn't seem quite right, but what is the proper method?
> Document with the same structure (where relevant) as a function is for the
html docs. See for example http://docs.scipy.org/numpy/docs/numpy.e/ They
then end up in np.doc.constants, so that would be the place to add the
docstring if you are not using the doc editor.

Assigning a docstring to a constant at runtime is not possible so there it
indeed does not make much sense.

Why wouldn't you document the constant in the docstring of the module where
> it's defined ?
> Personally, I used ..data to describe the constants in numpy.ma
> http://docs.scipy.org/doc/numpy/_sources/reference/maskedarray.baseclass.txt
> For some constants this is fine, but there can also be constants that go in
__all__ and end up in a different module or namespace. Or are defined in C

Of course you can have constants in your module docstring if it makes sense
there. You can also just refer to the html page (or to doc.constants) in the
module docstring.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/numpy-discussion/attachments/20091114/5bcb7fdd/attachment.html 

More information about the NumPy-Discussion mailing list