[SciPy-user] Docstring standards for NumPy and SciPy

[Edward Loper]

[Travis]
> I understood that epydoc translates :Parameters: and :Keywords:  
> sections
> for us (see the consolidated fields section of
> http://epydoc.sourceforge.net/fields.html#fields )

[Travis, responding to Edward]
>> As it stands, epydoc is perfectly happy with more than one
>> ":Parameters:" section..
>>
> Ahh!  This would be just fine.  I like this idea.

One issue with both of these solutions is that they will *not* make  
any distinction between the two sets of arguments in the generated  
html/pdf output.  It sounds like you *do* want this distinction to  
get preserved in the generated output.  If that's the case, then I  
think we'll need to define a new field tag.

[Travis]
> Personally I'd like to use :Parameters: and then add an :Extra
> Parameters: section or something like that if just using a blank- 
> line in
> the :Parameters: section is not useful enough.

[Fernando]
> I'd suggest 'Optional Parameters' or 'Named Parameters' if the
> existing 'Keywords' convention that epydoc/reST uses isn't deemed
> satisfactory (I happen to be OK with 'Keywords', but that's just me).

I'd be fine with any of "Extra Parameters", "Named Parameters", or  
"Optional Parameters"  (There will be some trickiness here, because  
rst will interpret these as eg an "Extra" field with an argument  
"Parameters"  c.f. ":Extra Parameters: ..." to ":param x: ...".  But  
I think that can be handled.)

Using :keywords: is not an option, assuming that you want the two  
sets of parameters to be distinguished in the output -- :keywords:  
already has a meaning in epydoc, and it will not put those parameters  
in a separate section.

[Travis]
> I agree that we can't really just ignore the problem.     I could live
> with :math:`eqn`  or :latex-math:`eqn` (although I would really prefer
> the abbreviations :m:`eqn` and :lm:`eqn`).   Abbreviations are just  
> fine
> in my mind for something that is used often enough.

I think the standard name should be something like :math:`foo`, but  
that it should be easy enough to expose a hook so you can  
register :m:`foo` as an alias for :math:`foo`.

[Travis]
>> I'm a little woried that epydoc is using :Keywords:  differently  
>> here as
>> in: these are keywords for the function that should go into some  
>> kind of
>> index.

No, :keywords: is used for keyword arguments.  As of now, I haven't  
added support for adding index terms in rst.  (In epytext, they're  
marked X{thusly}.)  Adding support wouldn't be particularly difficult  
-- presumably the syntax would be something like :indexed:`this`.   
It's just one of many many things I haven't gotten around to.

-Edward