[Doc-SIG] Why isn't docutils in the Python standard library yet?

[Jeff Rush]

ex cord wrote:
> On Thu, Jan 1, 2009 at 10:15 PM, Jeff Rush <jeff at taupro.com> 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