[Numpy-discussion] Documentation

[Charles R Harris]

On 5/15/07, Charles R Harris <charlesr.harris at gmail.com> wrote:
>
>
>
> On 5/15/07, Alan G Isaac <aisaac at american.edu> wrote:
> >
> > On Tue, 15 May 2007, Charles R Harris apparently wrote:
> > > If a CSS can set all the font styles, item spacing, and
> > > treatment of explanatory text, that would be the more
> > > flexible route.
> >
> > I'm not sure what "treatment" meams here,
> > but if it is a matter of font decisions or spacing,
> > the answer should be yes.
>
>
> The item in a consolidated list is divided into three parts: name, type,
> explanation. I see no way in the CSS to control the display of those parts,
> although it might be an undocumented feature. I basically want it to look
> like a definition list with maybe the current default for type, which puts
> it in parenthesis.
>
> > If we can also make SeeAlso generate links to the
> > > referenced  routines I will be very satisfied.
> >
> > epydoc supports documentation cross-reference links.
> > I think you get what you want (if I understand) just
> > but putting the name in back ticks, `like_this`.
> > That will give me a link to the like_this function
> > in the same module (and maybe anywhere in the package,
> > but I'm not sure).
>
>
> Yes, I just noticed that. One less thing to worry about.
>

Problems with the include HOWTO_DOCUMENT.txt file:

1) Needs to show, __docformat__ = "restructuredtext en", generates errors
otherwise.
2) Consolidated field *must* have a type if : is included in the item.
3) Notes and Examples are moved to the top.
4) :OtherParameters: is not a recogized type.

I am willing to correct this stuff, but <rant> I really don't think these
things should be committed without anyone apparently running epydoc and
looking at the output. </rant>

I've attached an html file generated by pasting the HOWTO_DOCUMENT.txt
markup into a fictitious foo function.

Chuck
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20070515/06e47bda/attachment.html>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20070515/06e47bda/attachment-0001.html>