[SciPy-dev] [Numpy-discussion] Doc-day

[Travis E. Oliphant]

Stefan van der Walt wrote:
> On Thu, Dec 27, 2007 at 09:27:09PM -0800, Jarrod Millman wrote:
>   
>> On Dec 27, 2007 7:42 PM, Travis E. Oliphant <oliphant at enthought.com> wrote:
>>     
>>> Doc-day will start tomorrow (in about 12 hours).  It will be Friday for
>>> much of America and be moving into Saturday for Europe and Asia.  Join
>>> in on the irc.freenode.net  (channel scipy) to coordinate effort.  I
>>> imaging people will be in an out.  I plan on being available in IRC from
>>> about 9:30 am CST to 6:00 pm CST and then possibly later.
>>>
>>> If you are available at different times in different parts of the
>>> world,  jump in and pick something to work on.
>>>       
>> Since this is our first doc-day, it will be fairly informal.  Travis
>> is going to be trying to get some estimate of which packages need the
>> most work.  But if there is some area of NumPy or SciPy you are
>> familiar with, please go ahead and pitch in.  Here is the current
>> NumPy/ SciPy coding standard including docstring standards:
>> http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines
>>     
>
> I have some questions regarding Travis' latest modifications to the
> documentation guidelines:
>
> The following section was removed, why?
>
> """
> A reST-documented module should define:: 
>
>   __docformat__ = 'restructuredtext en' 
> 	 	 
> at the top level in accordance with `PEP 258
> <http://www.python.org/dev/peps/pep-0258>`__.  Note that the
> ``__docformat__`` variable in a package's ``__init__.py`` file does
> not apply to objects defined in subpackages and submodules.
> """
>   

I don't see the point in every file having a __docformat__ line, when 
our documentaion formatting tool should already know the standard we are 
using is.   It's just more cruft.   Besides the PEP was rejected, so I 
don't know why we should be following it. 

We obviously need a pre-processor to map our files to epydoc, so let's 
do that instead of contorting docstrings into a format demanded by the 
tool.  The tool is a "tool" for us to use not be chained by.
> We had a long discussion on the mailing list on the pros and cons of
> "*Parameters*:" vs. "Parameters:".  I see now that it has been changed
> to
>
>   Parameters
>   ----------
>
> Is this still recognised as a list?
>
> I noted that the examples are now no longer indented: does ReST allow this?
>
>
> Note that building the example documentation, `epydoc example.py`, now
> warns:
>
> File /tmp/example.py, line 19, in example.foo
>    Warning: Line 24: Wrong underline character for heading.
>    Warning: Lines 27, 30, 32, 37, 39, 41, 43, 48, 50: Improper paragraph indentation.
>    
>
> While I understand the rationale behind
>
>   "The guiding principle is that human readers of the text itself are
>   given precedence over contorting the docstring so that epydoc_
>   produces nice output."
>
> I think that it would be impractical to break compatibility with the
> only documentation builder we currently have (unless there are others
> I am unaware of?).
>
>   

In my mind, the rationale trumps the "impracticality" especially since 
epydoc still produces readable output.  It is only the formatting that 
is not pretty-printed (although it doesn't look bad there either).  So, 
AFAIK, nothing is actually broken (except a little HTML formatting on 
output of epydoc).  But,  now the docstrings don't look crufty to my 
eyes.  

Basically, the problem is that I *really* don't like the *Parameters*:  
thing and all the indentation that takes place inside of docstrings to 
satisfy epydoc.  It is also inconsistent with the docstring standard 
that Enthought uses for the ETS tools suite.   It was really hard for me 
to start writing docstrings that followed that pattern. 

It seems better to have docstrings than to have them fit into an 
epydoc_-defined pattern.  

I'm sorry if I made changes unilaterally.   I didn't think there would 
be much concern as long as docstrings were moving forward.

-Travis