From gmane.0vd at gishpuppy.com Wed Aug 27 21:27:21 2008 From: gmane.0vd at gishpuppy.com (AC) Date: Wed, 27 Aug 2008 19:27:21 +0000 (UTC) Subject: [Doc-SIG] structured function documentation: preferred markup? Message-ID: Hello, First of all, I hope this is the right group to ask this in. My apologies if that's not the case. In order to simplify maintenance, I'm committed to providing structured documentation for all of my code. However, I'm not sure which markup language is preferred in the Python world - or whether there is any consensus at all. I'm currently using Epytext: def foo(bar): """ lorem ipsum dolor sit amet @param bar: consectetur adipisicing elit @type bar: str @return: None @rtype : None """ pass However, that seems excessively verbose due to the separate line for type information. I know there are alternatives (namely, Javadoc and reStructuredText) - but if they're not widely used, there's not much sense in me using those.* Any guidance would be greatly appreciated! * I know that Epydoc, for example, can generate documentation from various markup languages - however, my main concerns is the documentation directly within the source code From gmane.0vd at gishpuppy.com Thu Aug 28 15:25:11 2008 From: gmane.0vd at gishpuppy.com (AC) Date: Thu, 28 Aug 2008 13:25:11 +0000 (UTC) Subject: [Doc-SIG] structured function documentation: preferred markup? References: Message-ID: > I'm currently using Epytext [...] > However, that seems excessively verbose Also, I'm not sure how to indicate optional arguments, as well as valid values for certain arguments (e.g. action=["GET"|"PUT"|"POST"|"DELETE"]). From edloper at gradient.cis.upenn.edu Thu Aug 28 16:47:15 2008 From: edloper at gradient.cis.upenn.edu (Edward Loper) Date: Thu, 28 Aug 2008 10:47:15 -0400 Subject: [Doc-SIG] structured function documentation: preferred markup? (AC) Message-ID: <3131dfac0808280747j4f5d2c68xddf7afffabe69e19@mail.gmail.com> > In order to simplify maintenance, I'm committed to providing structured > documentation for all of my code. [...] > > However, that seems excessively verbose due to the separate line for type > information. Hi, I'm the author of epydoc. I just wanted to mention that the next item on my to-do list for epydoc is to add support for the following syntax: @param bar (str): description of bar... The analogous syntax would also be supported for restructuredtext: :param bar (str): description of bar... Note that you can already do the following in epydoc when using restructuredtext: :parameters: bar : str description of bar... baz: int description of baz... My guess is that it'll be a couple weeks before I get time to implement this, if you can wait that long. As for whether there's a standard markup for docstrings -- not really. Be sure to define the __docformat__ module-level variable, so that any program like epydoc can tell what markup language you're using. E.g.: __docformat__ = 'restructuredtext' or __docformat__ = 'epytext' My personal recommendation would be to use epytext if you're happy with a very lightweight markup language that doesn't support many advanced features (tables, images, etc); or restructuredtext otherwise. Both epytext and restructuredtext are quite human-readable, even for people who are not familiar with the markup languages, which I think is important. -Edward From gmane.0vd at gishpuppy.com Thu Aug 28 17:06:56 2008 From: gmane.0vd at gishpuppy.com (AC) Date: Thu, 28 Aug 2008 15:06:56 +0000 (UTC) Subject: [Doc-SIG] structured function documentation: preferred markup? References: <3131dfac0808280747j4f5d2c68xddf7afffabe69e19@mail.gmail.com> Message-ID: Thanks for your response! > I just wanted to mention that the next item on my to-do list for > epydoc is to add support for the following syntax: > @param bar (str): description of bar... That'd be great, as it would fix my biggest gripe with Epytext. Will that also allow for multiple types (e.g. "@param bar (str, list): ... ")? > My guess is that it'll be a couple weeks before I get time to > implement this, if you can wait that long. I'll simply start using that syntax now, and wait for the official announcement. (Is there an RSS feed I can subscribe to? Couldn't find any on http://epydoc.sourceforge.net.) > Be sure to define the __docformat__ module-level variable Thanks for the hint - will do! > My personal recommendation would be to use epytext if you're happy > with a very lightweight markup language that doesn't support many > advanced features That's exactly what I'm after. Any pointers on the issues mentioned in my previous addendum (optional arguments and valid argument values) - should those be put into the description part? Thanks again! From amk at amk.ca Sat Aug 30 18:17:38 2008 From: amk at amk.ca (A.M. Kuchling) Date: Sat, 30 Aug 2008 12:17:38 -0400 Subject: [Doc-SIG] Increasing size of the monospace font Message-ID: <20080830161738.GA5479@amk.local> Here's what the current 2.6 docs look like on Firefox 3.0 under MacOS: http://www.flickr.com/photos/44165698 at N00/2810698647/sizes/o/ The class names in the text are a good deal smaller than the English text. Is this just an oddity of my current configuration, or does it look like this for everyone? Here's what the docs look like after changing the font size for from 0.95 em to 1.25em: http://www.flickr.com/photos/44165698 at N00/2811539974/sizes/o/ I think this makes the class names match the x-height of the prose much better, though now the boldface makes them look very dark. --amk From fuzzyman at voidspace.org.uk Sat Aug 30 18:52:11 2008 From: fuzzyman at voidspace.org.uk (Michael Foord) Date: Sat, 30 Aug 2008 17:52:11 +0100 Subject: [Doc-SIG] Increasing size of the monospace font In-Reply-To: <20080830161738.GA5479@amk.local> References: <20080830161738.GA5479@amk.local> Message-ID: <48B97ABB.7040301@voidspace.org.uk> A.M. Kuchling wrote: > Here's what the current 2.6 docs look like on Firefox 3.0 under MacOS: > > http://www.flickr.com/photos/44165698 at N00/2810698647/sizes/o/ > > The class names in the text are a good deal smaller than the English > text. Is this just an oddity of my current configuration, or does it > look like this for everyone? > > Here's what the docs look like after changing the font size for > from 0.95 em to 1.25em: > > http://www.flickr.com/photos/44165698 at N00/2811539974/sizes/o/ > > I think this makes the class names match the x-height of the prose > much better, though now the boldface makes them look very dark. > I definitely prefer the second - including the 'darkness'. Michael > --amk > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig > -- http://www.ironpythoninaction.com/ http://www.voidspace.org.uk/ http://www.trypython.org/ http://www.ironpython.info/ http://www.theotherdelia.co.uk/ http://www.resolverhacks.net/ From g.brandl at gmx.net Sat Aug 30 23:14:28 2008 From: g.brandl at gmx.net (Georg Brandl) Date: Sat, 30 Aug 2008 23:14:28 +0200 Subject: [Doc-SIG] Increasing size of the monospace font In-Reply-To: <20080830161738.GA5479@amk.local> References: <20080830161738.GA5479@amk.local> Message-ID: A.M. Kuchling schrieb: > Here's what the current 2.6 docs look like on Firefox 3.0 under MacOS: > > http://www.flickr.com/photos/44165698 at N00/2810698647/sizes/o/ > > The class names in the text are a good deal smaller than the English > text. Is this just an oddity of my current configuration, or does it > look like this for everyone? > > Here's what the docs look like after changing the font size for > from 0.95 em to 1.25em: > > http://www.flickr.com/photos/44165698 at N00/2811539974/sizes/o/ > > I think this makes the class names match the x-height of the prose > much better, though now the boldface makes them look very dark. It's an oddity of browser configuration, but sadly present on most browsers. Since Sphinx only sets relative font sizes, it is affected by this, while most other sites set absolute font sizes. This is what "font-size: 1.25em" would look like in my browser: http://dev.pocoo.org/~gbrandl/pickle.png The "correct" way to fix this is to set the default text and monospace font sizes to sensible values in the browser configuration. Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out. From amk at amk.ca Sun Aug 31 20:22:04 2008 From: amk at amk.ca (A.M. Kuchling) Date: Sun, 31 Aug 2008 14:22:04 -0400 Subject: [Doc-SIG] What to do next for 2.6? Message-ID: <20080831182204.GA8152@amk.local> This weekend I made a final revision pass over the 2.6 "What's New" document and am now finished with it (barring any small corrections or omissions that come in). What should I do now with my Python doc time? Georg, do you have any suggestions? I could start reading through one of the manuals from end-to-end or go through the bug tracker for doc items. Are there any writing-related tasks you've been meaning to do before 2.6final? --amk From rrr at ronadam.com Sun Aug 31 21:11:46 2008 From: rrr at ronadam.com (Ron Adam) Date: Sun, 31 Aug 2008 14:11:46 -0500 Subject: [Doc-SIG] What to do next for 2.6? In-Reply-To: <20080831182204.GA8152@amk.local> References: <20080831182204.GA8152@amk.local> Message-ID: <48BAECF2.8050300@ronadam.com> A.M. Kuchling wrote: > This weekend I made a final revision pass over the 2.6 "What's New" > document and am now finished with it (barring any small corrections or > omissions that come in). > > What should I do now with my Python doc time? Georg, do you have any > suggestions? I could start reading through one of the manuals from > end-to-end or go through the bug tracker for doc items. Are there any > writing-related tasks you've been meaning to do before 2.6final? I'm presuming you are referring to content related items, but I fugures it doesn't hurt to ask. A while back I wrote a patch to enhance pydoc. http://bugs.python.org/issue2001 I figured it would need to wait until 2.7/3.1, is there any chance of getting it in before then? I probably need to updated it again so it will apply properly as there has been other fixes/patches to pydoc. Ron From lac at openend.se Sun Aug 31 22:44:42 2008 From: lac at openend.se (Laura Creighton) Date: Sun, 31 Aug 2008 22:44:42 +0200 Subject: [Doc-SIG] What to do next for 2.6? In-Reply-To: Message from "A.M. Kuchling" of "Sun, 31 Aug 2008 14:22:04 EDT." <20080831182204.GA8152@amk.local> References: <20080831182204.GA8152@amk.local> Message-ID: <200808312044.m7VKigPI027417@theraft.openend.se> In a message of Sun, 31 Aug 2008 14:22:04 EDT, "A.M. Kuchling" writes: >This weekend I made a final revision pass over the 2.6 "What's New" >document and am now finished with it (barring any small corrections or >omissions that come in). > >What should I do now with my Python doc time? Georg, do you have any >suggestions? I could start reading through one of the manuals from >end-to-end or go through the bug tracker for doc items. Are there any >writing-related tasks you've been meaning to do before 2.6final? > >--amk What is the status of the tutorial? Laura From g.brandl at gmx.net Sun Aug 31 22:52:03 2008 From: g.brandl at gmx.net (Georg Brandl) Date: Sun, 31 Aug 2008 22:52:03 +0200 Subject: [Doc-SIG] What to do next for 2.6? In-Reply-To: <20080831182204.GA8152@amk.local> References: <20080831182204.GA8152@amk.local> Message-ID: A.M. Kuchling schrieb: > This weekend I made a final revision pass over the 2.6 "What's New" > document and am now finished with it (barring any small corrections or > omissions that come in). > > What should I do now with my Python doc time? Georg, do you have any > suggestions? I could start reading through one of the manuals from > end-to-end or go through the bug tracker for doc items. Are there any > writing-related tasks you've been meaning to do before 2.6final? There is one thing I've been putting off for quite a long time :) Basically, the builtin types aren't documented well. The /library/stdtypes document is too long and not structured in a good fashion. Also, signatures for the constructors are documented in /library/functions which is not wrong but not satisfying either. Also, the type hierarchy in the "data model" section from the lang. ref. has overlaps with that section. For example, both document some special methods, both document the built-in types, etc. I would like to rename the lang. reference to "Core Python language". This document would then contain the language spec, ideally enhanced with some examples for those not liking having EBNF thrown into their face, the "data model" section with all its customization docs, and the content on built-in functions and types, all special methods and type methods properly documented etc. (e.g. I think some new float methods aren't documented yet). This is a large task, and I don't want to burden it on you. In my opinion it will make the Python documentation structure easier to grasp. I don't know how much time you have; I've never found enough of it to start. cheers, Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out. From ncoghlan at gmail.com Sun Aug 31 23:10:49 2008 From: ncoghlan at gmail.com (Nick Coghlan) Date: Mon, 01 Sep 2008 07:10:49 +1000 Subject: [Doc-SIG] What to do next for 2.6? In-Reply-To: References: <20080831182204.GA8152@amk.local> Message-ID: <48BB08D9.9060606@gmail.com> Georg Brandl wrote: > A.M. Kuchling schrieb: >> This weekend I made a final revision pass over the 2.6 "What's New" >> document and am now finished with it (barring any small corrections or >> omissions that come in). >> >> What should I do now with my Python doc time? Georg, do you have any >> suggestions? I could start reading through one of the manuals from >> end-to-end or go through the bug tracker for doc items. Are there any >> writing-related tasks you've been meaning to do before 2.6final? > > There is one thing I've been putting off for quite a long time :) > > Basically, the builtin types aren't documented well. The > /library/stdtypes document is too long and not structured in a good > fashion. Also, signatures for the constructors are documented in > /library/functions which is not wrong but not satisfying either. > Also, the type hierarchy in the "data model" section from the lang. > ref. has overlaps with that section. For example, both document some > special methods, both document the built-in types, etc. > > I would like to rename the lang. reference to "Core Python language". > This document would then contain the language spec, ideally enhanced with > some examples for those not liking having EBNF thrown into their face, > the "data model" section with all its customization docs, and the content > on built-in functions and types, all special methods and type methods > properly documented etc. (e.g. I think some new float methods aren't > documented yet). > > This is a large task, and I don't want to burden it on you. In my opinion > it will make the Python documentation structure easier to grasp. I don't > know how much time you have; I've never found enough of it to start. Along those lines, I plan to spend my Python time after 2.6/3.0 are out on an odf2rest converter for the user reference that's currently sitting in the sandbox. Even if we don't end up using that document as-is (it's a bit too dated at the moment for that to be a possibility anyway), I think it will provide useful input to any large-scale additions (particularly those targeting a middle ground between the tutorial and the language reference in regards to the language statements and the builtins). Cheers, Nick. -- Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia --------------------------------------------------------------- http://www.boredomandlaziness.org