On 5/15/07, Alan G Isaac <[EMAIL PROTECTED]> wrote:
> 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.
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
_______________________________________________
Numpy-discussion mailing list
Numpy-discussion@scipy.org
http://projects.scipy.org/mailman/listinfo/numpy-discussion
