Hi all I only read this thread today, and see that we have been battling many of the same challenges in our documentation efforts. I am glad to see that you are making such good progress!
2008/6/1 John Hunter <[EMAIL PROTECTED]>: >> 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-none > . 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'd like to explain the rationale behind our approach. Our main focus was to write produce documentation that is easy to read from a text-based terminal. While designing our standard, we set aside all other concerns, such as markup, compatibility with existing tools, etc. After the standard was more-or-less finalised, we wrote a tool which parses docstrings into logical units. For example, In [5]: d = SphinxFunctionDoc(np.ravel) In [6]: d['Parameters'] Out[6]: [('a', '{array_like}', ['']), ('order', "{'C','F'}, optional", ["If order is 'C' the elements are taken in row major order. If order", "is 'F' they are taken in column major order."])] In [7]: print d **ravel(a, order='C')** ----------------------- Return a 1d array containing the elements of a (copy only if needed). [...] Note that, when printing the docstring, it looks entirely different from the original docstring, and contains customised markup. If you wanted to use a table to describe keyword arguments, for example, it would require only a few extra lines of code. If you are interested in playing with the code, it is available at https://code.launchpad.net/~stefanv/scipy/numpy-refguide We also developed a web-framework that allows our community to write documentation: http://sd-2116.dedibox.fr/pydocweb While it was written with NumPy in mind (we have some weird docstring injection, not unlike yours), it should be trivial to modify for use by another project. Good luck! Stéfan ------------------------------------------------------------------------- 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
