On Saturday 31 May 2008 10:45:34 pm John Hunter wrote: > On Sat, May 31, 2008 at 7:50 PM, Darren Dale <[EMAIL PROTECTED]> wrote: > > I just realized, though, that I should probably be striving to conform > > with the standard that the numpy and scipy folks put together: > > http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines and > > http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py . Any comments? > > I think I have been relying too heavily on tables for the keyword > > arguments. > > I think that following their guidelines is a good idea for the most > part, but we needn't adhere to them religiously. For one thing, > matplotlib uses *a lot* more keyword args than either numpy or scipy, > and what works for them for kwargs may not be best for us. In > particular, if we use the format they suggest, I'm afraid our > docstrings will simply take up too much space. For example, see > http://mentat.za.net/numpy/refguide/functions.xhtml#all-a-axis-none-out-non >e . What if we formatted all the Line2d kwargs that way? It seems a bit > bloated in terms of vertical space for the number of kwargs we need to > handle, and so a ReST table may in fact be better.
I agree. We should default to parameter lists, but longer lists of kwargs will be formatted as tables. There are also some features in the numpy template (like the use of sections) that cause sphinx to fail. I wonder how the webpage you referenced was generated? > We want our documentation to be mostly consistent to aid the folks > trying to put together bits and pieces of documentation from several > projects to write in-house docs (which incorporate local docs) or > books, but I'm not sure we need our doc formatting to be entirely > consistent at the API level. Right, we shouldn't worry about rigorously adhering to a standard, but their template seems like a good guideline to keep in mind. ------------------------------------------------------------------------- This SF.net email is sponsored by: Microsoft Defy all challenges. Microsoft(R) Visual Studio 2008. http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/ _______________________________________________ Matplotlib-devel mailing list Matplotlib-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
