From anh at math.luc.edu Sun Jan 2 00:05:17 2005 From: anh at math.luc.edu (Andrew Harrington) Date: Sun Jan 2 00:05:45 2005 Subject: [Doc-SIG] reST ordered list syntax extension Message-ID: <200501012305.j01N5HHt004022@georg.math.luc.edu> Desired feature change in restructured text (reST) ordered lists: Being able to add ordered list entries to the middle of a list without renumbering would be very useful. If I start with: 1. first 2. second a. sub a para b. sub b 3. third And I want to insert entry NEW after 1, I must renumber: 1. first 2. NEW 3. second a. sub a para b. sub b 4. third I suggest that the first entry in a list start with the actual format desired, but for later entries allow '#': 1. first #. second a. sub a para #. sub b #. third which would make the insertion easy: 1. first #. NEW #. second a. sub a para #. sub b #. third The parser already keeps track of what the next sequence identifier would be and issues errors if they are wrong. Why not just allow the # with the same punctuation after it and indentation before as in the first entry, and rather than declaring an error, substitute in the next in the sequence? An extension could allow fully labeled sublist entries If you wanted: 1. first 2. second 2.a. sub a para 2.b. sub b 3. third you could use in the extended reST: 1. first #. second #.a. sub a para #.#. sub b #. third The assumption is that if a first sub entry starts with one or more '#' and punctuation (the '#.' here), they are assumed to be repeats of the current outer levels, and there must be an explicit subsequence starter in addition (the 'a' here). I have written in that further sub entries must have the same prefix ('#.' here) as the first subentry. A more concise alternative would be to _assume the same prefix, and just allow #.#. sub b to be #. sub b I am not sure if the latter alternative should be indented to match the first instead of the second '#' in the alternate version above. The punctuation is important to be included explicitly if desired. If I gave input #a. sub a I would get out the more concise output 2a. sub a Comments? Thanks Andy Harrington From goodger at python.org Sat Jan 15 22:39:18 2005 From: goodger at python.org (David Goodger) Date: Sat Jan 15 22:39:26 2005 Subject: [Doc-SIG] reST ordered list syntax extension In-Reply-To: <200501012305.j01N5HHt004022@georg.math.luc.edu> References: <200501012305.j01N5HHt004022@georg.math.luc.edu> Message-ID: <41E98D86.2050009@python.org> [Andrew Harrington] > Desired feature change in restructured text (reST) ordered lists: > > Being able to add ordered list entries to the middle of a list > without renumbering would be very useful. Yes, it potentially would. It hasn't been implemented, but the idea has been proposed before: http://docutils.sf.net/docs/dev/rst/alternatives.html#auto-enumerated-lists. > I suggest that the first entry in a list start with the actual > format desired, but for later entries allow '#': That's variation 2. > The parser already keeps track of what the next sequence identifier > would be and issues errors if they are wrong. Why not just allow > the # with the same punctuation after it and indentation before as > in the first entry, and rather than declaring an error, substitute > in the next in the sequence? I haven't needed it enough to ever implement it myself. We did receive a patch (for idea 3 in the link above), but I'm not keen on that variation. I'd welcome a patch for variation 2 and/or 1. > An extension could allow fully labeled sublist entries That idea has been kicking around for a long time too (see http://docutils.sf.net/docs/dev/rst/alternatives.html#compound-enumerated-lists). Again, no one has ever needed it enough to implement it. > 1. first > 2. second > > 2.a. sub a > > para > > 2.b. sub b > > 3. third I wouldn't indent the sublists though. It could introduce ambiguity, as you pointed out in your examples combining the two ideas. -- David Goodger -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 253 bytes Desc: OpenPGP digital signature Url : http://mail.python.org/pipermail/doc-sig/attachments/20050115/b0f6694c/signature.pgp From alan.green at gmail.com Mon Jan 24 12:20:07 2005 From: alan.green at gmail.com (Alan Green) Date: Mon Jan 24 12:20:10 2005 Subject: [Doc-SIG] Hello and the threading module Message-ID: Hi All, I've been working with Python for fun and profit (but mostly fun) for the last four years or so, and feel it's time for me to give something back. I've decided to see if I can help out with documentation a little. Looking through the documentation bugs on sourceforge, it seems that the threading module docs could do with a clean up - particularly to document edge cases, like what might happen if you were to pass None as a parameter. Would that be a good place to start? Meanwhile, I've already put up two patches. The first updates the "Working on Cygwin" section of Documenting Python. The second modifies a public API in order to make it simpler to document - perhaps a little too ambitiousfor somebody's second ever patch :). Alan -- Alan Green alan.green@cardboard.nu - http://cardboard.nu From radeex at gmail.com Fri Jan 28 12:15:48 2005 From: radeex at gmail.com (Christopher Armstrong) Date: Fri Jan 28 12:15:51 2005 Subject: [Doc-SIG] Good API doc generation in the Python world recently? Message-ID: <60ed19d4050128031574476b66@mail.gmail.com> I can't find any. HappyDoc is way, way out of date (it blows up on newer code, in certain situations, I think) and epydoc just has loads and loads of problems with its importing of code (at least with Twisted, and anything else using Zope Interfaces). Has anyone heard anything about better docstring-based API doc generation lately? I'm afraid I'm going to have to release Twisted 2.0 without API docs, but I'm considering improving HappyDoc after that. -- Twisted | Christopher Armstrong: International Man of Twistery Radix | -- http://radix.twistedmatrix.com | Release Manager, Twisted Project \\\V/// | -- http://twistedmatrix.com |o O| | Founding Member, Hobart Hacking Society w----v----w-+ -- http://hackingsociety.org/chapters/hash From Sylvain.Thenault at logilab.fr Fri Jan 28 12:24:15 2005 From: Sylvain.Thenault at logilab.fr (Sylvain =?iso-8859-1?Q?Th=E9nault?=) Date: Fri Jan 28 12:24:18 2005 Subject: [Doc-SIG] Good API doc generation in the Python world recently? In-Reply-To: <60ed19d4050128031574476b66@mail.gmail.com> References: <60ed19d4050128031574476b66@mail.gmail.com> Message-ID: <20050128112415.GA4216@logilab.fr> On Friday 28 January ? 22:15, Christopher Armstrong wrote: > I can't find any. HappyDoc is way, way out of date (it blows up on > newer code, in certain situations, I think) and epydoc just has loads > and loads of problems with its importing of code (at least with > Twisted, and anything else using Zope Interfaces). Has anyone heard > anything about better docstring-based API doc generation lately? > > I'm afraid I'm going to have to release Twisted 2.0 without API docs, > but I'm considering improving HappyDoc after that. Gasp ! Wasn't epydoc originaly coming from the twisted project, as I thought ? I really do like epydoc, and would be sad if it's not maintained anymore... Having epydoc not importing the code would be probably the best option (based on the compiler std module, probably), and so it could become a kind of "standardized" docstring format (using the ReST backend, of course ;). I don't know much of the epydoc source code right know, but I would be happy to help such a task instead of seing epydoc abandoned. -- Sylvain Th?nault LOGILAB, Paris (France). http://www.logilab.com http://www.logilab.fr http://www.logilab.org From mike at pcblokes.com Fri Jan 28 12:29:19 2005 From: mike at pcblokes.com (Michael Foord) Date: Fri Jan 28 12:29:24 2005 Subject: [Doc-SIG] Good API doc generation in the Python world recently? In-Reply-To: <20050128112415.GA4216@logilab.fr> References: <60ed19d4050128031574476b66@mail.gmail.com> <20050128112415.GA4216@logilab.fr> Message-ID: <41FA220F.7000307@pcblokes.com> epydoc isn't abandoned - but happydoc is. I like epydoc, but would also prefer to see a version that parsed source code rather than importing it. Would make it much harder to link classes to super classes etc though I guess. Regards, Fuzzy http://www.voidspace.org.uk/python/index.shtml Sylvain Th?nault wrote: >On Friday 28 January ? 22:15, Christopher Armstrong wrote: > > >>I can't find any. HappyDoc is way, way out of date (it blows up on >>newer code, in certain situations, I think) and epydoc just has loads >>and loads of problems with its importing of code (at least with >>Twisted, and anything else using Zope Interfaces). Has anyone heard >>anything about better docstring-based API doc generation lately? >> >>I'm afraid I'm going to have to release Twisted 2.0 without API docs, >>but I'm considering improving HappyDoc after that. >> >> > >Gasp ! >Wasn't epydoc originaly coming from the twisted project, as I thought ? >I really do like epydoc, and would be sad if it's not maintained >anymore... Having epydoc not importing the code would be probably the >best option (based on the compiler std module, probably), and so it >could become a kind of "standardized" docstring format (using the ReST >backend, of course ;). I don't know much of the epydoc source code right >know, but I would be happy to help such a task instead of seing epydoc >abandoned. > > > From Sylvain.Thenault at logilab.fr Fri Jan 28 12:35:20 2005 From: Sylvain.Thenault at logilab.fr (Sylvain =?iso-8859-1?Q?Th=E9nault?=) Date: Fri Jan 28 12:35:22 2005 Subject: [Doc-SIG] Good API doc generation in the Python world recently? In-Reply-To: <41FA220F.7000307@pcblokes.com> References: <60ed19d4050128031574476b66@mail.gmail.com> <20050128112415.GA4216@logilab.fr> <41FA220F.7000307@pcblokes.com> Message-ID: <20050128113520.GD4216@logilab.fr> On Friday 28 January ? 11:29, Michael Foord wrote: > epydoc isn't abandoned - but happydoc is. good news :) > I like epydoc, but would also prefer to see a version that parsed source > code rather than importing it. Would make it much harder to link classes > to super classes etc though I guess. I've already that (and much other things) in my toolbox :) I'm the pylint author and I've build a package which extends the compiler package classes to ease source code analysis without relying on "living" objects. Everything is in astng subpackage of logilab's common library (http://www.logilab.org/projects/common). Starting from that I think the task wouldn't be that hard... -- Sylvain Th?nault LOGILAB, Paris (France). http://www.logilab.com http://www.logilab.fr http://www.logilab.org From aahz at pythoncraft.com Fri Jan 28 16:51:35 2005 From: aahz at pythoncraft.com (Aahz) Date: Fri Jan 28 16:51:37 2005 Subject: [Doc-SIG] Good API doc generation in the Python world recently? In-Reply-To: <41FA220F.7000307@pcblokes.com> References: <60ed19d4050128031574476b66@mail.gmail.com> <20050128112415.GA4216@logilab.fr> <41FA220F.7000307@pcblokes.com> Message-ID: <20050128155135.GA22467@panix.com> On Fri, Jan 28, 2005, Michael Foord wrote: > > epydoc isn't abandoned - but happydoc is. > > I like epydoc, but would also prefer to see a version that parsed > source code rather than importing it. Would make it much harder to > link classes to super classes etc though I guess. One of the primary goals for Python 2.5 is to finally push through the AST branch. If you want parsed source, consider joining python-dev and helping with that project. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ "19. A language that doesn't affect the way you think about programming, is not worth knowing." --Alan Perlis From Sylvain.Thenault at logilab.fr Fri Jan 28 17:06:22 2005 From: Sylvain.Thenault at logilab.fr (Sylvain =?iso-8859-1?Q?Th=E9nault?=) Date: Fri Jan 28 17:06:24 2005 Subject: [Doc-SIG] Good API doc generation in the Python world recently? In-Reply-To: <20050128155135.GA22467@panix.com> References: <60ed19d4050128031574476b66@mail.gmail.com> <20050128112415.GA4216@logilab.fr> <41FA220F.7000307@pcblokes.com> <20050128155135.GA22467@panix.com> Message-ID: <20050128160622.GA4787@logilab.fr> On Friday 28 January ? 10:51, Aahz wrote: > On Fri, Jan 28, 2005, Michael Foord wrote: > > > > epydoc isn't abandoned - but happydoc is. > > > > I like epydoc, but would also prefer to see a version that parsed > > source code rather than importing it. Would make it much harder to > > link classes to super classes etc though I guess. > > One of the primary goals for Python 2.5 is to finally push through the > AST branch. If you want parsed source, consider joining python-dev and > helping with that project. What do you mean ? Core python being based on a more usable ast than the one returned by the parser module ? More than that ? Would be very interested if you could tell be more about your point, or giving me some pointers... TIA -- Sylvain Th?nault LOGILAB, Paris (France). http://www.logilab.com http://www.logilab.fr http://www.logilab.org From aahz at pythoncraft.com Fri Jan 28 19:18:08 2005 From: aahz at pythoncraft.com (Aahz) Date: Fri Jan 28 19:18:12 2005 Subject: [Doc-SIG] Good API doc generation in the Python world recently? In-Reply-To: <20050128160622.GA4787@logilab.fr> References: <60ed19d4050128031574476b66@mail.gmail.com> <20050128112415.GA4216@logilab.fr> <41FA220F.7000307@pcblokes.com> <20050128155135.GA22467@panix.com> <20050128160622.GA4787@logilab.fr> Message-ID: <20050128181808.GA19054@panix.com> On Fri, Jan 28, 2005, Sylvain Th?nault wrote: > On Friday 28 January ? 10:51, Aahz wrote: >> On Fri, Jan 28, 2005, Michael Foord wrote: >>> >>> epydoc isn't abandoned - but happydoc is. >>> >>> I like epydoc, but would also prefer to see a version that parsed >>> source code rather than importing it. Would make it much harder to >>> link classes to super classes etc though I guess. >> >> One of the primary goals for Python 2.5 is to finally push through the >> AST branch. If you want parsed source, consider joining python-dev and >> helping with that project. > > What do you mean ? Core python being based on a more usable ast than > the one returned by the parser module ? That's my understanding, keeping in mind that I haven't paid much attention. > More than that ? Would be very interested if you could tell be more > about your point, or giving me some pointers... Sorry, you'll need to do some research or hope one of the other people reading knows more. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ "19. A language that doesn't affect the way you think about programming, is not worth knowing." --Alan Perlis From bac at OCF.Berkeley.EDU Fri Jan 28 22:25:00 2005 From: bac at OCF.Berkeley.EDU (Brett C.) Date: Fri Jan 28 22:25:35 2005 Subject: [Doc-SIG] Good API doc generation in the Python world recently? In-Reply-To: <20050128160622.GA4787@logilab.fr> References: <60ed19d4050128031574476b66@mail.gmail.com> <20050128112415.GA4216@logilab.fr> <41FA220F.7000307@pcblokes.com> <20050128155135.GA22467@panix.com> <20050128160622.GA4787@logilab.fr> Message-ID: <41FAADAC.4070801@ocf.berkeley.edu> Sylvain Th?nault wrote: > On Friday 28 January ? 10:51, Aahz wrote: > >> On Fri, Jan 28, 2005, Michael Foord wrote: >> >>> epydoc isn't abandoned - but happydoc is. >>> >>> I like epydoc, but would also prefer to see a version that parsed >>> source code rather than importing it. Would make it much harder to >>> link classes to super classes etc though I guess. >> >> >> One of the primary goals for Python 2.5 is to finally push through the >> AST branch. If you want parsed source, consider joining python-dev and >> helping with that project. > > > > What do you mean ? Core python being based on a more usable ast than the > one returned by the parser module ? More than that ? Yep. The AST branch is doing away with using the parse tree (what the parser module returns) to generate bytecode and is instead taking a more traditional two-step process; parse tree -> AST, AST -> bytecode. The hope is to get it done for Python 2.5 . Now whether that includes a marshalling ability to emit the AST as Python objects that one can use in code is another story. I am sure people would love to have access to it but it is not a top priority right now. > Would be very interested if you could tell be more about your point, or > giving me some pointers... > It is in Python CVS as a branch called ast-branch. There is going to be work done at PyCon as a sprint and development will most likely continue after that until it is finished. -Brett From lac at strakt.com Fri Jan 28 22:52:12 2005 From: lac at strakt.com (Laura Creighton) Date: Fri Jan 28 22:52:21 2005 Subject: [Doc-SIG] Good API doc generation in the Python world recently? In-Reply-To: Message from Aahz of "Fri, 28 Jan 2005 13:18:08 EST." <20050128181808.GA19054@panix.com> References: <60ed19d4050128031574476b66@mail.gmail.com> <20050128112415.GA4216@logilab.fr> <41FA220F.7000307@pcblokes.com> <20050128155135.GA22467@panix.com> <20050128160622.GA4787@logilab.fr> <20050128181808.GA19054@panix.com> Message-ID: <200501282152.j0SLqD3h008516@ratthing-b246.strakt.com> Sylvain, Ludovic Aubry and Adrien Di Mascio should be driving back to Logilab from the PyPy Sprint full of ideas. We need an AST for PyPy too, and we are of course interested in your PyLint work. Come hang out on #pypy at irc.freenode.net next week and we can discuss this more. Whatever we do for pypy it would be good if we could drop it into epydoc, make it part of CPython, and make everybody happy. Laura Creighton