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
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.