> On 5/15/07, Alan G Isaac <[EMAIL PROTECTED]> 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. 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. 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.) Formatting: this is just a style issue. Submit a CSS file. 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. I will not try to summarize all the reasons *for* relying on reST, since these were hashed over in the previous discussion. 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. Cheers, Alan Isaac _______________________________________________ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion