[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
code.

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.

Cheers,
Ralf
-------------- 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