From excord80 at gmail.com Thu Jan 1 06:21:51 2009 From: excord80 at gmail.com (ex cord) Date: Thu, 1 Jan 2009 00:21:51 -0500 Subject: [Doc-SIG] Why isn't docutils in the Python standard library yet? Message-ID: I notice that the Python documentation is written in reStructuredText, but that docutils is not part of the Python standard library. Is there any reason why docutils doesn't come stock with Python? Is it missing critical features? What's holding it back? For comparison, when you install Perl, the basic tools for reading POD (and converting it to other formats) come standard. And this is *Perl*, where there's supposed to be more than one way to do it and they very rarely impose any standard way to do anything upon the user. Quick observation to mention: I can't remember the last time I looked at the docs for a Python distribution and they weren't formatted in reStructuredText. From excord80 at gmail.com Thu Jan 1 06:32:53 2009 From: excord80 at gmail.com (ex cord) Date: Thu, 1 Jan 2009 00:32:53 -0500 Subject: [Doc-SIG] doc-sig status page broken links Message-ID: On the doc-sig status page I notice that the links to "Robin Friedrich's starship website", "Daniel Larsson's pythondoc package", and "Daniel's older gendoc package" are all dead. The link to "Linuxdoc" is also dead. From skip at pobox.com Thu Jan 1 15:10:15 2009 From: skip at pobox.com (skip at pobox.com) Date: Thu, 1 Jan 2009 08:10:15 -0600 Subject: [Doc-SIG] doc-sig status page broken links In-Reply-To: References: Message-ID: <18780.52935.265967.957376@montanaro-dyndns-org.local> >> On the doc-sig status page >> I >> notice that the links to "Robin Friedrich's starship website", >> "Daniel Larsson's pythondoc package", and "Daniel's older gendoc >> package" are all dead. The link to "Linuxdoc" is also dead. I removed those links. I suspect that page needs to either completely deleted or rewritten. -- Skip Montanaro - skip at pobox.com - http://smontanaro.dyndns.org/ From jeff at taupro.com Fri Jan 2 04:15:48 2009 From: jeff at taupro.com (Jeff Rush) Date: Thu, 01 Jan 2009 21:15:48 -0600 Subject: [Doc-SIG] Why isn't docutils in the Python standard library yet? In-Reply-To: References: Message-ID: <495D86E4.9060305@taupro.com> ex cord wrote: > I notice that the Python documentation is written in reStructuredText, > but that docutils is not part of the Python standard library. Is there > any reason why docutils doesn't come stock with Python? Is it missing > critical features? What's holding it back? There is a document outlining what needs to be improved in docutils before it is ready for inclusion in the standard library: http://docutils.sourceforge.net/docs/dev/todo.html#minimum-requirements-for-python-standard-library-candidacy or if that URL causes you trouble, the same page using tinyurl: http://tinyurl.com/862f3e > For comparison, when you install Perl, the basic tools for reading POD > (and converting it to other formats) come standard. And this is > *Perl*, where there's supposed to be more than one way to do it and > they very rarely impose any standard way to do anything upon the user. > > Quick observation to mention: I can't remember the last time I looked > at the docs for a Python distribution and they weren't formatted in > reStructuredText. Also remember that some projects do not want to be included in the standard library because they have different release cycles and bug trackers. That said, I look forward to the day it is included as it has become a key part of so much I do these days. There are parts of docutils showing their age that need work, support for eggs-based plugins that has caused several public problems re pathing conflicts, folding in the excellent work done in the Sphinx framework for marking up Python, which needs to be added to the wiki page: http://docutils.sf.net/sandbox/README.html#documenting-python It seems the set of developers is too small. Certainly with David Goodger (a major force behind docutils) acting as chair of PyCon last year and this year, and taking on as of Dec 2008 a full-time position with the PSF, there is a need for additional developers to come forward and get excited about the possibilities. -Jeff From excord80 at gmail.com Fri Jan 2 05:25:18 2009 From: excord80 at gmail.com (ex cord) Date: Thu, 1 Jan 2009 23:25:18 -0500 Subject: [Doc-SIG] Why isn't docutils in the Python standard library yet? In-Reply-To: <495D86E4.9060305@taupro.com> References: <495D86E4.9060305@taupro.com> Message-ID: On Thu, Jan 1, 2009 at 10:15 PM, Jeff Rush wrote: > ex cord wrote: >> I notice that the Python documentation is written in reStructuredText, >> but that docutils is not part of the Python standard library. Is there >> any reason why docutils doesn't come stock with Python? Is it missing >> critical features? What's holding it back? > > There is a document outlining what needs to be improved in docutils before it > is ready for inclusion in the standard library: > > http://docutils.sourceforge.net/docs/dev/todo.html#minimum-requirements-for-python-standard-library-candidacy > > or if that URL causes you trouble, the same page using tinyurl: > > http://tinyurl.com/862f3e Ah. Thanks for the link. It's interesting; a number of those things on the list seem pretty fancy. Well, they just seem pretty fancy to me -- especially if it's regarding using docutils/reST for (A) use in docstrings, and (B) use in readme files and other dedicated docs. All I'd care about for documenting modules is: can it do italics? bold? chapters/sections/subsections? lists? tables? include images? Yeah? Great -- use it. Including it with Python's std lib would get even more devs using that markup, and there would be more motivation to add any extra features to docutils down the road. I don't know if Perl's POD has the features on that list. I don't think it does. Yet, Perl has volumes of great docs, and almost everyone in the Perl community uses that POD markup (which I personally never could get used to). In fact, I'm tempted to say that Perl has really excellent docs in spite of POD. :) Docutils seems to be in this stasis where it's believed that it needs more sophisticated features to be included with Python, but users would just like some nice markup to use for their docs/docstrings -- with support for that markup built into Python. > >> For comparison, when you install Perl, the basic tools for reading POD >> (and converting it to other formats) come standard. And this is >> *Perl*, where there's supposed to be more than one way to do it and >> they very rarely impose any standard way to do anything upon the user. >> >> Quick observation to mention: I can't remember the last time I looked >> at the docs for a Python distribution and they weren't formatted in >> reStructuredText. > > Also remember that some projects do not want to be included in the standard > library because they have different release cycles and bug trackers. Do you happen to know if the docutils devs want docutils included with Python? Personally, I think it should be the other way around. If all the Python devs are using reST everywhere anyway, it would be in their best interest for them to just say, "look, we use it, we like it, we've actually all become addicted to using it, and everyone else is using it too, so let's work out some way to get it in Python for the next release, eh?" > That said, I look forward to the day it is included as it has become a key > part of so much I do these days. There are parts of docutils showing their > age that need work, support for eggs-based plugins that has caused several > public problems re pathing conflicts, That's an easy one to solve: don't require docutils to support egg-based plug-ins. :) If I want to install a docutils plug-in (I've never used one, and didn't even know they existed), then I'll just do a ``python setup.py install`` like everyone else. :) Personally, I don't care for eggs anyway -- when I install a distribution I want to see the source and the docs. From ncoghlan at gmail.com Fri Jan 2 06:51:42 2009 From: ncoghlan at gmail.com (Nick Coghlan) Date: Fri, 02 Jan 2009 15:51:42 +1000 Subject: [Doc-SIG] Why isn't docutils in the Python standard library yet? In-Reply-To: References: <495D86E4.9060305@taupro.com> Message-ID: <495DAB6E.2040107@gmail.com> ex cord wrote: > Personally, I think it should be the other way around. If all the > Python devs are using reST everywhere anyway, it would be in their > best interest for them to just say, "look, we use it, we like it, > we've actually all become addicted to using it, and everyone else is > using it too, so let's work out some way to get it in Python for the > next release, eh?" Actually, we cheat a bit and drag a copy of docutils into our Docs source tree via an external subversion reference: ~/devel/python/Doc/tools$ svn info docutils Path: docutils URL: http://svn.python.org/projects/external/docutils-0.4/docutils Repository Root: http://svn.python.org/projects Repository UUID: 6015fed2-1504-0410-9fe1-9d1591cc4771 Revision: 66083 Node Kind: directory Schedule: normal Last Changed Author: georg.brandl Last Changed Rev: 56857 Last Changed Date: 2007-08-10 01:52:00 +1000 (Fri, 10 Aug 2007) In light of the existence of Sphinx as a higher layer built on top of docutils that is appropriate for Python's own documentation, perhaps the lower level goals considered appropriate before targeting standard library inclusion need to be reconsidered. Cheers, Nick. -- Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia --------------------------------------------------------------- From jeff at taupro.com Fri Jan 2 07:32:31 2009 From: jeff at taupro.com (Jeff Rush) Date: Fri, 02 Jan 2009 00:32:31 -0600 Subject: [Doc-SIG] Why isn't docutils in the Python standard library yet? In-Reply-To: References: <495D86E4.9060305@taupro.com> Message-ID: <495DB4FF.1090103@taupro.com> ex cord wrote: > On Thu, Jan 1, 2009 at 10:15 PM, Jeff Rush wrote: >> ex cord wrote: >>> I notice that the Python documentation is written in reStructuredText, >>> but that docutils is not part of the Python standard library. Is there >>> any reason why docutils doesn't come stock with Python? Is it missing >>> critical features? What's holding it back? >> There is a document outlining what needs to be improved in docutils before it >> is ready for inclusion in the standard library: >> >> http://docutils.sourceforge.net/docs/dev/todo.html#minimum-requirements-for-python-standard-library-candidacy >> >> or if that URL causes you trouble, the same page using tinyurl: >> >> http://tinyurl.com/862f3e > > Ah. Thanks for the link. It's interesting; a number of those things on > the list seem pretty fancy. Well, they just seem pretty fancy to me -- > especially if it's regarding using docutils/reST for (A) use in > docstrings, and (B) use in readme files and other dedicated docs. All > I'd care about for documenting modules is: can it do italics? bold? > chapters/sections/subsections? lists? tables? include images? Yeah? > Great -- use it. Including it with Python's std lib would get even > more devs using that markup, and there would be more motivation to add > any extra features to docutils down the road. Eh, I didn't realize you mean for *docstrings* specifically. There -are- competing markup conventions in that arena but not in the README area. The PEP about docstring markup itemizes them I believe, and there are those who think reST is too heavy-weight for docstrings. >> Also remember that some projects do not want to be included in the standard >> library because they have different release cycles and bug trackers. > > Do you happen to know if the docutils devs want docutils included with Python? I don't know but suspect they do, based on that wiki page of what is needed. They're just not in a hurry until all the details are right. > That's an easy one to solve: don't require docutils to support > egg-based plug-ins. :) If I want to install a docutils plug-in (I've > never used one, and didn't even know they existed)... They don't exist, and that is a problem. I said egg-based plugins because it is one of the more popular plugin technologies for Python (the others I'm aware of are the Twisted plugins and Zope3 component plugins using utilities). So the problem is that people (like me but also many others) want to extend docutils with new writers or directives, but lacking a plugin mechanism, end up hacking a custom version of docutils. Then people install the hacked version for feature X and the standard version for their general environment (say via an RPM or egg) and you get tracebacks, because setuptools has one rule for ordering eggs (std version) versus non-eggs (custom version), and non-setuptools environments has another, and they interfere with each other. It's a long story but basically we need a clean way to extend docutils without just changing its source, and using the existing eggs plugin mechanism seems a quick way to achieve that. Like docutils is a defacto doc standard, eggs are a defacto packaging standard for Python, lacking a strong alternative. -Jeff From grubert at users.sourceforge.net Sun Jan 4 14:03:52 2009 From: grubert at users.sourceforge.net (engelbert gruber) Date: Sun, 4 Jan 2009 14:03:52 +0100 Subject: [Doc-SIG] Why isn't docutils in the Python standard library yet? In-Reply-To: <495D86E4.9060305@taupro.com> References: <495D86E4.9060305@taupro.com> Message-ID: On Fri, Jan 2, 2009 at 4:15 AM, Jeff Rush wrote: > ex cord wrote: >> I notice that the Python documentation is written in reStructuredText, >> but that docutils is not part of the Python standard library. Is there >> any reason why docutils doesn't come stock with Python? Is it missing >> critical features? What's holding it back? > > There is a document outlining what needs to be improved in docutils before it > is ready for inclusion in the standard library: > > http://docutils.sourceforge.net/docs/dev/todo.html#minimum-requirements-for-python-standard-library-candidacy > > or if that URL causes you trouble, the same page using tinyurl: > > http://tinyurl.com/862f3e > > >> For comparison, when you install Perl, the basic tools for reading POD >> (and converting it to other formats) come standard. And this is >> *Perl*, where there's supposed to be more than one way to do it and >> they very rarely impose any standard way to do anything upon the user. as reStructured text is readable without tools, if you look at old README files the look similar, so in fact no tool is required. POD has more markup even for simple files. and of course david has set the bar for inclusion really high. >> Quick observation to mention: I can't remember the last time I looked >> at the docs for a Python distribution and they weren't formatted in >> reStructuredText. > > Also remember that some projects do not want to be included in the standard > library because they have different release cycles and bug trackers. > > That said, I look forward to the day it is included as it has become a key > part of so much I do these days. There are parts of docutils showing their > age that need work, support for eggs-based plugins that has caused several > public problems re pathing conflicts, folding in the excellent work done in > the Sphinx framework for marking up Python, which needs to be added to the > wiki page: > > http://docutils.sf.net/sandbox/README.html#documenting-python > > It seems the set of developers is too small. Certainly with David Goodger (a > major force behind docutils) acting as chair of PyCon last year and this > year, and taking on as of Dec 2008 a full-time position with the PSF, there is > a need for additional developers to come forward and get excited about the > possibilities. > > -Jeff > _______________________________________________ > Doc-SIG maillist - Doc-SIG at python.org > http://mail.python.org/mailman/listinfo/doc-sig >