[Numpy-discussion] Documentation

[Charles R Harris]

On 5/15/07, Alan G Isaac <aisaac at american.edu> wrote:
>
> > On 5/15/07, Alan G Isaac <aisaac at american.edu> wrote:
> >> Just to add a bit more specificity, I believe that the
> >> HOWTO_DOCUMENT.txt document at
> >> http://svn.scipy.org/svn/numpy/trunk/numpy/doc/HOWTO_DOCUMENT.txt
> >> summarizes a substantial discussion and broad agreement.
> >> I.e., it is currently the preferred standard.
>
>
> On Tue, 15 May 2007, Charles R Harris apparently wrote:
> > I think the output generated for the consolidated lists is too ugly to
> bear.
> > The bullets are distracting, there is no spacing between entries, and
> the
> > explanatory text is appended on the same line, making it difficult to
> read.
> > So get rid of ":Parameters:" and just use "Parameters: ". Futhermore,
> the
> > dashes under Notes and Examples make these section headers and PyDoc
> moves
> > these blocks to the top so that they are printed before the Parameters
> list
> > and other list blocks. Did no one actually run this stuff through PyDoc?
> So
> > my recommendations are to remove the leading :'s from the list headings,
> > making them definition lists, italicize them, and insert the mandatory
> blank
> > line after. Then remove the dashes  from under Notes and Examples, and
> let
> > the documenter choose between lists with the appended : , or just indent
> the
> > text after, which has the same effect if there are no list item
> headings,
> > which there typically aren't in those sections.
>
>
> If this is meant as a reply to my post, it seems to treat my
> simple summary as advocacy.


I was pointing out why I thought the suggested style was deficient.

Now I am in fact an advocate of sticking with
> reStructuredText, but I was simply summarizing how
> I understood a rather *extended* discussion.
> There was an outcome; I believe the doc above captures it.
>
> Charles apparently wishes to reopen that discussion.


Yes!

It will probably help to keep a few things separate.
>
> Bullets in consolidated lists:
>     if you don't like them, don't use them.
>     Use a definition list instead.
>     (I like this much better myself.)


We should settle on one or the other.

Formatting:
>     this is just a style issue.
>     Submit a CSS file.


I will look into that.

Placement of Notes and Examples:
>     Seems simple to change, and the Epydoc developer has
>     been very accommodating. Raise it as an issue or submit
>     a patch.


It also causes the headings to be set in large bold type. Ugly.

I will not try to summarize all the reasons *for* relying on
> reST, since these were hashed over in the previous
> discussion.


I think reST is great, and properly used we get good looking output without
mucking up the help text displayed in a terminal.


> I will just mention the obvious: getting
> additional functionality can have some costs, and one cost
> of having access to all the possible epydoc
> conversions---including typeset math in both PDF and XHTML
> documents---is the use of (very light) informative markup.


I have no problem with that.  I am just trying to get the most suitable
output without making upstream changes to epydoc. We will have to do
something to deal with the documentation for c functions in add_newdocs.py,
but that is another problem.

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